ToggleGroup

A set of toggle buttons that read as one control: text alignment, a view switcher, text styles. ToggleGroup.Root has role="group", and each ToggleGroup.Item is a secondary Button.Root with aria-pressed. The group takes one stop in the Tab order, on the pressed item in single mode and on the first item in multiple mode, and the arrow keys move focus between items without pressing them.

In the default single mode, one item is pressed at most, and pressing it again clears the value to null.

<ToggleGroup.Root aria-label="Alignment" value={align} onValueChange={setAlign}>
  <ToggleGroup.Item value="left">Left</ToggleGroup.Item>
  <ToggleGroup.Item value="center">Center</ToggleGroup.Item>
  <ToggleGroup.Item value="right">Right</ToggleGroup.Item>
</ToggleGroup.Root>

With selectionMode="multiple", any number can be pressed, and the value is an array.

Name the group with aria-label or aria-labelledby. Horizontal items join like Button.Group. Inside a Toolbar, the toolbar owns the arrow keys and the tab stop.

When to use

When: Options that change how something shows, where the pressed state is visible at a glance and changes take effect at once.

When not: A choice in a form that is submitted → Radio or Checkbox. One setting on or off → Switch, or a single toggle Button.Root. Switching between panels of content → Tabs.

Props

ToggleGroup.Root props
Name	Type	Required	Default	Description
aria-label	`string`	no	—	Names the group, such as "Alignment".
selectionMode	`"single" \| "multiple"`	no	"single"	Single presses one item at most; pressing it again clears it. Multiple presses any number.
value	`string \| null \| readonly string[]`	no	—	Controlled pressed value: a value or null for single, an array for multiple.
defaultValue	`string \| null \| readonly string[]`	no	—	Starting pressed value when uncontrolled.
onValueChange	`((value: string \| null) => void) \| ((value: string[]) => void)`	no	—	Called with the new pressed value when an item is pressed.
orientation	`"horizontal" \| "vertical"`	no	"horizontal", or the toolbar's	Layout, and the arrow keys that move focus outside a toolbar. Horizontal items join like Button.Group.
disabled	`boolean`	no	false	Disables every item.
children	`React.ReactNode`	no	—	ToggleGroup.Item elements.

ToggleGroup.Item props
Name	Type	Required	Default	Description
value	`string`	yes	—	Identifies the item in the group value.
disabled	`boolean`	no	false	Disables this item.
children	`React.ReactNode`	no	—	Label, or a Button.Icon with aria-label.