ToggleButton

Button that toggles between selected and unselected states.

Examples

Default

ToggleToggle

function Default() {
  const [isSelected, setIsSelected] = useState(false);
  return (
    <ToggleButton
      isSelected={isSelected}
      label="Toggle"
      onChange={setIsSelected}
    />
  );
}

With Icon

FavoriteFavorite

function WithIcon() {
  const [isSelected, setIsSelected] = useState(false);
  return (
    <ToggleButton
      icon={Star}
      isSelected={isSelected}
      label="Favorite"
      onChange={setIsSelected}
      selectedIcon={Heart}
    />
  );
}

Icon Only

function IconOnly() {
  const [isSelected, setIsSelected] = useState(false);
  return (
    <ToggleButton
      icon={Star}
      isIconOnly
      isSelected={isSelected}
      label="Favorite"
      onChange={setIsSelected}
    />
  );
}

Sizes

SmallSmallMediumMediumLargeLarge

<div style={{display: 'flex', gap: '1rem', alignItems: 'center'}}>
  <ToggleButton icon={Star} label="Small" size="sm" />
  <ToggleButton icon={Star} label="Medium" size="md" />
  <ToggleButton icon={Star} label="Large" size="lg" />
</div>

Loading

SyncingSyncing

<ToggleButton label="Syncing" isLoading />

With Tooltip

Add to favorites

function WithTooltip() {
  const [isSelected, setIsSelected] = useState(false);
  return (
    <ToggleButton
      icon={Star}
      isIconOnly
      isSelected={isSelected}
      label="Favorite"
      onChange={setIsSelected}
      tooltip="Add to favorites"
    />
  );
}

Disabled

DisabledDisabled

<ToggleButton label="Disabled" isDisabled />

Single Group

function SingleGroup() {
  const [value, setValue] = useState<string | null>('left');
  return (
    <ToggleButtonGroup
      label="Alignment"
      onChange={setValue}
      type="single"
      value={value}>
      <ToggleButton
        icon={AlignLeft}
        isIconOnly
        label="Align left"
        value="left"
      />
      <ToggleButton
        icon={AlignCenter}
        isIconOnly
        label="Align center"
        value="center"
      />
      <ToggleButton
        icon={AlignRight}
        isIconOnly
        label="Align right"
        value="right"
      />
    </ToggleButtonGroup>
  );
}

Multiple Group

function MultipleGroup() {
  const [value, setValue] = useState<string[]>(['bold']);
  return (
    <ToggleButtonGroup
      label="Formatting"
      onChange={setValue}
      type="multiple"
      value={value}>
      <ToggleButton icon={Bold} isIconOnly label="Bold" value="bold" />
      <ToggleButton icon={Italic} isIconOnly label="Italic" value="italic" />
      <ToggleButton
        icon={Underline}
        isIconOnly
        label="Underline"
        value="underline"
      />
    </ToggleButtonGroup>
  );
}

Vertical Group

function VerticalGroup() {
  const [value, setValue] = useState<string | null>('left');
  return (
    <ToggleButtonGroup
      label="Alignment"
      onChange={setValue}
      orientation="vertical"
      type="single"
      value={value}>
      <ToggleButton
        icon={AlignLeft}
        isIconOnly
        label="Align left"
        value="left"
      />
      <ToggleButton
        icon={AlignCenter}
        isIconOnly
        label="Align center"
        value="center"
      />
      <ToggleButton
        icon={AlignRight}
        isIconOnly
        label="Align right"
        value="right"
      />
    </ToggleButtonGroup>
  );
}

Disabled Group

function DisabledGroup() {
  const [value, setValue] = useState<string | null>('bold');
  return (
    <ToggleButtonGroup
      isDisabled
      label="Formatting"
      onChange={setValue}
      type="single"
      value={value}>
      <ToggleButton icon={Bold} isIconOnly label="Bold" value="bold" />
      <ToggleButton icon={Italic} isIconOnly label="Italic" value="italic" />
      <ToggleButton
        icon={Underline}
        isIconOnly
        label="Underline"
        value="underline"
      />
    </ToggleButtonGroup>
  );
}

Group Sizes

<div style={{display: 'flex', flexDirection: 'column', gap: '1rem'}}>
  {(['sm', 'md', 'lg'] as const).map(size => (
    <ToggleButtonGroup
      key={size}
      label={`Alignment (${size})`}
      onChange={() => {}}
      size={size}
      value="left">
      <ToggleButton
        icon={AlignLeft}
        isIconOnly
        label="Align left"
        value="left"
      />
      <ToggleButton
        icon={AlignCenter}
        isIconOnly
        label="Align center"
        value="center"
      />
      <ToggleButton
        icon={AlignRight}
        isIconOnly
        label="Align right"
        value="right"
      />
    </ToggleButtonGroup>
  ))}
</div>

API

ToggleButton

Button that toggles between selected and unselected states.

Prop	Type	Default	Description
className	string	—	Additional CSS class names applied to the button root.
data-testid	string	—	Test ID applied to the button root.
icon	IconComponent	—	Icon element rendered before the label.
isDisabled	boolean	false	Whether the button is disabled.
isIconOnly	boolean	false	Whether to visually hide the label and render a square icon button.
isLoading	boolean	false	Whether the button is loading.
isSelected	boolean	false	Whether the button is currently selected.
label*	string	—	Accessible label for the button.
onChange	( isSelected: boolean, event: MouseEvent<HTMLButtonElement>, ) => void	—	Called when the selected state should change. Receives the next selected state and the originating click event.
ref	Ref<HTMLButtonElement>	—	Ref forwarded to the button root.
selectedIcon	IconComponent	—	Icon element rendered when the button is selected.
size	"sm" | "md" | "lg"	—	Visual size of the button.
style	CSSProperties	—	Inline styles applied to the button root.
tooltip	string	—	Tooltip text shown on hover.
value	string	—	Value identifier when used inside ToggleButtonGroup.
form	string	—	HTML form attribute associating the button with a <form> by ID.
id	string	—	HTML id attribute applied to the root element.
aria-controls	string	—	Identifies the element(s) whose contents are controlled by the button.
aria-describedby	string	—	Identifies the element(s) that describe the button.
aria-details	string	—	Identifies the element that provides a detailed description.
aria-expanded	boolean	—	Indicates whether a controlled element is expanded or collapsed.
aria-haspopup	boolean | 'menu' | 'listbox' | 'tree' | 'grid' | 'dialog'	—	Indicates the button opens an interactive popup element.
aria-keyshortcuts	string	—	Keyboard shortcuts that activate or focus the button.
aria-labelledby	string	—	Identifies the element(s) that label the button.
onFocus	FocusEventHandler<HTMLElement>	—	Focus event handler for the root element.
onKeyDown	(event: KeyboardEvent<HTMLElement>) => void	—	Keyboard event handler for the root element.

ToggleButtonGroup

Groups related ToggleButtons and manages shared selection state.

When type: "single"

Prop	Type	Default	Description
onChange*	( value: string | null, event: MouseEvent<HTMLButtonElement>, ) => void	—	Called with the selected value when selection changes, or null when the active button is deselected. Also receives the originating click event.
type	'single'	'single'	Single-selection mode. Clicking the active button clears selection.
value*	string | null	—	Currently selected value, or null for no selection.
children*	ReactNode	—	Toggle button children.
className	string	—	Additional CSS class names applied to the group root.
data-testid	string	—	Test ID applied to the group root.
isDisabled	boolean	false	Whether all buttons in the group are disabled.
label*	string	—	Accessible label for the group.
orientation	"horizontal" | "vertical"	'horizontal'	Group orientation.
ref	Ref<HTMLDivElement>	—	Ref forwarded to the group root.
size	"sm" | "md" | "lg"	—	Default size for buttons in the group.
style	CSSProperties	—	Inline styles applied to the group root.

When type: "multiple"

Prop	Type	Default	Description
onChange*	(value: string[], event: MouseEvent<HTMLButtonElement>) => void	—	Called with the array of selected values when selection changes. Also receives the originating click event.
type*	'multiple'	—	Multiple-selection mode.
value*	string[]	—	Currently selected values.
children*	ReactNode	—	Toggle button children.
className	string	—	Additional CSS class names applied to the group root.
data-testid	string	—	Test ID applied to the group root.
isDisabled	boolean	false	Whether all buttons in the group are disabled.
label*	string	—	Accessible label for the group.
orientation	"horizontal" | "vertical"	'horizontal'	Group orientation.
ref	Ref<HTMLDivElement>	—	Ref forwarded to the group root.
size	"sm" | "md" | "lg"	—	Default size for buttons in the group.
style	CSSProperties	—	Inline styles applied to the group root.