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 Ref<HTMLButtonElement>: The ref type for this component.

ToggleButtonProps

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

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

Defaults to false .
iconStart ReactNode: An icon displayed before the button text.
iconEnd ReactNode: An icon displayed after the button text.
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 string: The name of the input element, used when submitting an HTML form. See MDN.
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 boolean: Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.
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 CSSProperties: Sets the CSS style for the element. Only use as a last resort. Use style props instead.

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

StyleProps

margin Responsive<Spacing | "auto">: The amount of margin applied to all edges of this component.
marginX Responsive<Spacing | "auto">: The amount of margin applied to the left and right edges of this component. Takes priority over margin.
marginY Responsive<Spacing | "auto">: The amount of margin applied to the top and bottom edges of this component. Takes priority over margin.
marginTop Responsive<Spacing | "auto">: The amount of margin applied to the top edge of this component. Takes priority over marginY and margin.
marginRight Responsive<Spacing | "auto">: The amount of margin applied to the right edge of this component. Takes priority over marginX and margin.
marginBottom Responsive<Spacing | "auto">: The amount of margin applied to the bottom edge of this component. Takes priority over marginY and margin.
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 Ref<HTMLButtonElement>: The ref type for this component.

ToggleIconButtonProps

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

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

Defaults to false .
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 string: The name of the input element, used when submitting an HTML form. See MDN.
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 boolean: Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.
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 CSSProperties: Sets the CSS style for the element. Only use as a last resort. Use style props instead.

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

StyleProps

margin Responsive<Spacing | "auto">: The amount of margin applied to all edges of this component.
marginX Responsive<Spacing | "auto">: The amount of margin applied to the left and right edges of this component. Takes priority over margin.
marginY Responsive<Spacing | "auto">: The amount of margin applied to the top and bottom edges of this component. Takes priority over margin.
marginTop Responsive<Spacing | "auto">: The amount of margin applied to the top edge of this component. Takes priority over marginY and margin.
marginRight Responsive<Spacing | "auto">: The amount of margin applied to the right edge of this component. Takes priority over marginX and margin.
marginBottom Responsive<Spacing | "auto">: The amount of margin applied to the bottom edge of this component. Takes priority over marginY and margin.
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 Ref<HTMLDivElement>: The ref type for this component.

ToggleButtonGroupProps

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

See styling guide.
aria-label string: Defines a string value that labels the current element.
aria-labelledby string: Identifies the element (or elements) that labels the current element.
aria-describedby string: Identifies the element (or elements) that describes the object.
aria-details string: Identifies the element (or elements) that provide a detailed, extended description for the object.
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 string: The name of the input element, used when submitting an HTML form. See MDN.
description string: A description for the field. Provides a hint such as specific requirements for what to choose.
error FieldError: An error message for the field.
validate (value: Set) => undefined | string | true | string[]: 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 'multiple' | 'single': Whether single or multiple selection is enabled.
selectedKeys Iterable<Key, any, any>: The currently selected keys in the collection (controlled).
defaultSelectedKeys Iterable<Key, any, any>: The initial selected keys in the collection (uncontrolled).
onSelectionChange (keys: Set<Key>) => void: Handler that is called when the selection changes.
isDisabled boolean: Whether all items are disabled.

StyleProps

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