Toggle button API

Import

Cimpress UI exports three toggle-button-related components:

ToggleButton: displays a toggle button that has a visible label
ToggleIconButton: displays a toggle button that has no visible label (icon-only)
ToggleButtonGroup: container component that groups related toggle buttons together, providing a shared label, optional description, error handling, and state management.

import { ToggleButton, ToggleIconButton, ToggleButtonGroup } from '@cimpress-ui/react';

Controlled/uncontrolled usage

This component can be used in a controlled or uncontrolled way.

In the controlled way, this component doesn’t maintain its own internal state, and its value is provided by the parent component. Use the controlled way when you need to be able to change the state of this component in other parts of your application.

In the uncontrolled way, this component maintains its own internal state, and can optionally notify the parent component when its internal state changes. Use the uncontrolled way when you don’t need to change the state of this component in other parts of your application.

import { Stack, ToggleButton } from '@cimpress-ui/react';
import { useState } from 'react';

export default function Demo() {
  const [isSelected, setIsSelected] = useState(false);

  return (
    <Stack gap={32}>
      <ToggleButton isSelected={isSelected} onChange={setIsSelected}>
        I am controlled by React state
      </ToggleButton>

      <ToggleButton>I am uncontrolled and unselected by default</ToggleButton>

      <ToggleButton defaultSelected>I am uncontrolled and selected by default</ToggleButton>
    </Stack>
  );
}

Toggle button group

Preview
Code

Text alignment (controlled)

Text alignment (uncontrolled)

import { type Key, Stack, ToggleButton, ToggleButtonGroup } from '@cimpress-ui/react';
import { useState } from 'react';

export default function Demo() {
  const [selectedKeys, setSelectedKeys] = useState<Set<Key>>(() => new Set(['left']));

  return (
    <Stack gap={32}>
      <ToggleButtonGroup
        label="Text alignment (controlled)"
        selectedKeys={selectedKeys}
        onSelectionChange={setSelectedKeys}
      >
        <ToggleButton value="left">Left</ToggleButton>
        <ToggleButton value="center">Center</ToggleButton>
        <ToggleButton value="right">Right</ToggleButton>
      </ToggleButtonGroup>

      <ToggleButtonGroup label="Text alignment (uncontrolled)" defaultSelectedKeys={['left']}>
        <ToggleButton value="left">Left</ToggleButton>
        <ToggleButton value="center">Center</ToggleButton>
        <ToggleButton value="right">Right</ToggleButton>
      </ToggleButtonGroup>
    </Stack>
  );
}

Accessibility notes

The toggle button state can be changed by pressing Enter or Space, similar to a native HTML checkbox.

ToggleButtonGroup is a single tab stop within the page’s tab order. Use the Tab key to navigate to the group, and the arrow keys to navigate between toggle buttons within the group.

ToggleButton and ToggleButtonGroup require a textual label to remain accessible to assistive technologies. ToggleIconButton should have an aria-label prop defined to identify the function of the button to assistive technologies. See our accessibility guide for more details.

The toggle button label must remain the same regardless of the selection state.

Group state management

Selection state of toggle buttons within ToggleButtonGroup cannot be set individually. Please use ToggleButtonGroup’s selectedKeys/defaultSelectedKeys props instead.

// This won't work! :(
<ToggleButtonGroup label="Text alignment">
  <ToggleButton value="left">Left</ToggleButton>
  <ToggleButton value="center">Center</ToggleButton>
  <ToggleButton value="right" defaultSelected>Right</ToggleButton>
</ToggleButtonGroup>

// But this will :)
<ToggleButtonGroup label="Text alignment" defaultSelectedKeys={['right']}>
  <ToggleButton value="left">Left</ToggleButton>
  <ToggleButton value="center">Center</ToggleButton>
  <ToggleButton value="right">Right</ToggleButton>
</ToggleButtonGroup>

Forms

Toggle button, toggle icon button, and toggle button group can integrate with native HTML forms. See our forms guide to learn how to work with forms.

API reference

ToggleButton

Displays a labelled button that allows users to toggle between two states. Can be used standalone, or as part of ToggleButtonGroup.

See toggle button usage guidelines.

ref Section titled “ ref ” Ref<HTMLButtonElement>: The ref type for this component.

ToggleButtonProps

children * Section titled “ children * ” StringLikeChildren: The text displayed on the button. Must remain the same regardless of selection state.
size Section titled “ size ” 'small' | 'medium' | 'large': The size of the button.

Defaults to 'medium' .
fullWidth Section titled “ fullWidth ” boolean: Whether the button should take up the whole available width.

Defaults to false .
iconStart Section titled “ iconStart ” ReactNode: An icon displayed before the button text.
iconEnd Section titled “ iconEnd ” ReactNode: An icon displayed after the button text.
form Section titled “ form ” string: The <form> element to associate the input with. The value of this attribute must be the id of a <form> in the same document. See MDN.
name Section titled “ name ” string: The name of the input element, used when submitting an HTML form. See MDN.
value Section titled “ value ” string: The value of the input element, used when submitting an HTML form. See MDN.

When used in a ToggleButtonGroup, value serves as an identifier for this button, and has to be unique across all buttons in the group.
data-cim-style-root Section titled “ data-cim-style-root ” boolean: Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.
UNSAFE_className Section titled “ UNSAFE_className ” string: Sets the CSS className for the element. Only use as a last resort. Use style props instead.

See styling guide.
UNSAFE_style Section titled “ UNSAFE_style ” CSSProperties: Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.
aria-label Section titled “ aria-label ” string: Defines a string value that labels the current element.
aria-labelledby Section titled “ aria-labelledby ” string: Identifies the element (or elements) that labels the current element.
aria-describedby Section titled “ aria-describedby ” string: Identifies the element (or elements) that describes the object.
aria-details Section titled “ aria-details ” string: Identifies the element (or elements) that provide a detailed, extended description for the object.
isDisabled Section titled “ isDisabled ” boolean: Whether the button is disabled.
isSelected Section titled “ isSelected ” boolean: Whether the element should be selected (controlled).
defaultSelected Section titled “ defaultSelected ” boolean: Whether the element should be selected (uncontrolled).
onChange Section titled “ onChange ” (isSelected: boolean) => void: Handler that is called when the element's selection state changes.
onHoverStart Section titled “ onHoverStart ” (e: HoverEvent) => void: Handler that is called when a hover interaction starts.
onHoverEnd Section titled “ onHoverEnd ” (e: HoverEvent) => void: Handler that is called when a hover interaction ends.
onPress Section titled “ onPress ” (e: PressEvent) => void: Handler that is called when the press is released over the target.
autoFocus Section titled “ autoFocus ” boolean: Whether the element should receive focus on render.

StyleProps

margin Section titled “ margin ” Responsive<Spacing | "auto">: The amount of margin applied to all edges of this component.
marginX Section titled “ marginX ” Responsive<Spacing | "auto">: The amount of margin applied to the left and right edges of this component. Takes priority over margin.
marginY Section titled “ marginY ” Responsive<Spacing | "auto">: The amount of margin applied to the top and bottom edges of this component. Takes priority over margin.
marginTop Section titled “ marginTop ” Responsive<Spacing | "auto">: The amount of margin applied to the top edge of this component. Takes priority over marginY and margin.
marginRight Section titled “ marginRight ” Responsive<Spacing | "auto">: The amount of margin applied to the right edge of this component. Takes priority over marginX and margin.
marginBottom Section titled “ marginBottom ” Responsive<Spacing | "auto">: The amount of margin applied to the bottom edge of this component. Takes priority over marginY and margin.
marginLeft Section titled “ marginLeft ” Responsive<Spacing | "auto">: The amount of margin applied to the left edge of this component. Takes priority over marginX and margin.

ToggleIconButton

Displays an icon-only button that allows users to toggle between two states. Can be used standalone, or as part of ToggleButtonGroup.

See toggle button usage guidelines.

ref Section titled “ ref ” Ref<HTMLButtonElement>: The ref type for this component.

ToggleIconButtonProps

icon * Section titled “ icon * ” ReactNode: The icon displayed on the button.
aria-label * Section titled “ aria-label * ” string: The label describing the function of this button for assistive technologies. Must remain the same regardless of selection state.
size Section titled “ size ” 'small' | 'medium' | 'large': The size of the button.

Defaults to 'medium' .
fullWidth Section titled “ fullWidth ” boolean: Whether the button should take up the whole available width.

Defaults to false .
form Section titled “ form ” string: The <form> element to associate the input with. The value of this attribute must be the id of a <form> in the same document. See MDN.
name Section titled “ name ” string: The name of the input element, used when submitting an HTML form. See MDN.
value Section titled “ value ” string: The value of the input element, used when submitting an HTML form. See MDN.

When used in a ToggleButtonGroup, value serves as an identifier for this button, and has to be unique across all buttons in the group.
data-cim-style-root Section titled “ data-cim-style-root ” boolean: Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.
UNSAFE_className Section titled “ UNSAFE_className ” string: Sets the CSS className for the element. Only use as a last resort. Use style props instead.

See styling guide.
UNSAFE_style Section titled “ UNSAFE_style ” CSSProperties: Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.
aria-labelledby Section titled “ aria-labelledby ” string: Identifies the element (or elements) that labels the current element.
aria-describedby Section titled “ aria-describedby ” string: Identifies the element (or elements) that describes the object.
aria-details Section titled “ aria-details ” string: Identifies the element (or elements) that provide a detailed, extended description for the object.
isDisabled Section titled “ isDisabled ” boolean: Whether the button is disabled.
isSelected Section titled “ isSelected ” boolean: Whether the element should be selected (controlled).
defaultSelected Section titled “ defaultSelected ” boolean: Whether the element should be selected (uncontrolled).
onChange Section titled “ onChange ” (isSelected: boolean) => void: Handler that is called when the element's selection state changes.
onHoverStart Section titled “ onHoverStart ” (e: HoverEvent) => void: Handler that is called when a hover interaction starts.
onHoverEnd Section titled “ onHoverEnd ” (e: HoverEvent) => void: Handler that is called when a hover interaction ends.
onPress Section titled “ onPress ” (e: PressEvent) => void: Handler that is called when the press is released over the target.
autoFocus Section titled “ autoFocus ” boolean: Whether the element should receive focus on render.

StyleProps

margin Section titled “ margin ” Responsive<Spacing | "auto">: The amount of margin applied to all edges of this component.
marginX Section titled “ marginX ” Responsive<Spacing | "auto">: The amount of margin applied to the left and right edges of this component. Takes priority over margin.
marginY Section titled “ marginY ” Responsive<Spacing | "auto">: The amount of margin applied to the top and bottom edges of this component. Takes priority over margin.
marginTop Section titled “ marginTop ” Responsive<Spacing | "auto">: The amount of margin applied to the top edge of this component. Takes priority over marginY and margin.
marginRight Section titled “ marginRight ” Responsive<Spacing | "auto">: The amount of margin applied to the right edge of this component. Takes priority over marginX and margin.
marginBottom Section titled “ marginBottom ” Responsive<Spacing | "auto">: The amount of margin applied to the bottom edge of this component. Takes priority over marginY and margin.
marginLeft Section titled “ marginLeft ” Responsive<Spacing | "auto">: The amount of margin applied to the left edge of this component. Takes priority over marginX and margin.

ToggleButtonGroup

Allows users to toggle multiple options, with single or multiple selection.

See toggle button usage guidelines.

ref Section titled “ ref ” Ref<HTMLDivElement>: The ref type for this component.

ToggleButtonGroupProps

children * Section titled “ children * ” ReactNode: Toggle buttons belonging to the group. Each button must have a value prop defined.
label * Section titled “ label * ” string: The content to display as the label.
isInvalid Section titled “ isInvalid ” boolean: Whether the current selection is invalid.
isRequired Section titled “ isRequired ” boolean: Whether a selection is required before form submission.
data-cim-style-root Section titled “ data-cim-style-root ” boolean: Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.
UNSAFE_className Section titled “ UNSAFE_className ” string: Sets the CSS className for the element. Only use as a last resort. Use style props instead.

See styling guide.
UNSAFE_style Section titled “ UNSAFE_style ” CSSProperties: Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.
aria-label Section titled “ aria-label ” string: Defines a string value that labels the current element.
aria-labelledby Section titled “ aria-labelledby ” string: Identifies the element (or elements) that labels the current element.
aria-describedby Section titled “ aria-describedby ” string: Identifies the element (or elements) that describes the object.
aria-details Section titled “ aria-details ” string: Identifies the element (or elements) that provide a detailed, extended description for the object.
form Section titled “ form ” string: The <form> element to associate the input with. The value of this attribute must be the id of a <form> in the same document. See MDN.
name Section titled “ name ” string: The name of the input element, used when submitting an HTML form. See MDN.
description Section titled “ description ” string: A description for the field. Provides a hint such as specific requirements for what to choose.
error Section titled “ error ” FieldError: An error message for the field.
validate Section titled “ validate ” (value: Set) => string | true | string[] | undefined: A function that returns an error message (or true) if a given value is invalid. Validation errors are displayed to the user when the form is submitted. For real-time validation, use the error prop instead.
selectionMode Section titled “ selectionMode ” 'multiple' | 'single': Whether single or multiple selection is enabled.

Defaults to 'single' .
selectedKeys Section titled “ selectedKeys ” Iterable<Key, any, any>: The currently selected keys in the collection (controlled).
defaultSelectedKeys Section titled “ defaultSelectedKeys ” Iterable<Key, any, any>: The initial selected keys in the collection (uncontrolled).
onSelectionChange Section titled “ onSelectionChange ” (keys: Set<Key>) => void: Handler that is called when the selection changes.
isDisabled Section titled “ isDisabled ” boolean: Whether all items are disabled.

StyleProps

margin Section titled “ margin ” Responsive<Spacing | "auto">: The amount of margin applied to all edges of this component.
marginX Section titled “ marginX ” Responsive<Spacing | "auto">: The amount of margin applied to the left and right edges of this component. Takes priority over margin.
marginY Section titled “ marginY ” Responsive<Spacing | "auto">: The amount of margin applied to the top and bottom edges of this component. Takes priority over margin.
marginTop Section titled “ marginTop ” Responsive<Spacing | "auto">: The amount of margin applied to the top edge of this component. Takes priority over marginY and margin.
marginRight Section titled “ marginRight ” Responsive<Spacing | "auto">: The amount of margin applied to the right edge of this component. Takes priority over marginX and margin.
marginBottom Section titled “ marginBottom ” Responsive<Spacing | "auto">: The amount of margin applied to the bottom edge of this component. Takes priority over marginY and margin.
marginLeft Section titled “ marginLeft ” Responsive<Spacing | "auto">: The amount of margin applied to the left edge of this component. Takes priority over marginX and margin.

Toggle button API

Import

Controlled/uncontrolled usage

Single toggle button

Toggle button group

Accessibility notes

Group state management

Forms

API reference

ToggleButton

ref

children *

size

fullWidth

iconStart

iconEnd

form

name

value

data-cim-style-root

UNSAFE_className

UNSAFE_style

aria-label

aria-labelledby

aria-describedby

aria-details

isDisabled

isSelected

defaultSelected

onChange

onHoverStart

onHoverEnd

onPress

autoFocus

margin

marginX

marginY

marginTop

marginRight

marginBottom

marginLeft

ToggleIconButton

ref

icon *

aria-label *

size

fullWidth

form

name

value

data-cim-style-root

UNSAFE_className

UNSAFE_style

aria-labelledby

aria-describedby

aria-details

isDisabled

isSelected

defaultSelected

onChange

onHoverStart

onHoverEnd

onPress

autoFocus

margin

marginX

marginY

marginTop

marginRight

marginBottom

marginLeft

ToggleButtonGroup

ref

children *

label *

isInvalid

isRequired

data-cim-style-root

UNSAFE_className

UNSAFE_style