Toggle group

API and Development

View SourceOpens in a new tab Submit IssueOpens in a new tab

ToggleGroupRoot wraps ToggleGroup.Item children as a mutually exclusive selection (type="single"). ToggleGroupItem renders a button with vertical separators and Text labels. Sizes: ToggleGroupSize.Small, Medium, Large (default).

ToggleGroupRoot

Name	Type	Default	Description
`aria-description`	`LocalizedMessage`	—	Extended description for assistive tech.
`aria-label`	`LocalizedMessage`	—	Accessible name when the visible label is insufficient.
`aria-labelledby`	`string`	—	Id of the element that names this group; use {@link ToggleGroupLabelledByProps} instead. Id of the element that names this group.
`aria-placeholder`	`LocalizedMessage`	—	Hint for an empty control.
`children`	`ReactNode`	—	Toggle parts. Each must be a {@link ToggleGroupItem }.
`className`	`string`	—	Optional module class from colocated CSS.
`collapseUnselectedLabels`	`boolean`	—	Collapses unselected items to their icon and animates the selected label open. Items need {@link ToggleGroupItemProps.icon} and `aria-label` or visible button copy.
`defaultValue`	`DisplayValue \| DisplayValue[] \| null`	—	Initial selected id when uncontrolled. Initial selected ids when uncontrolled.
`disabled`	`boolean`	—	Disables every item.
`fullSpan`	`boolean`	—	When true, items span the full width of the parent evenly.
`initialItemId`	`DisplayValue`	—	Item id that receives `tabIndex={0}` when nothing is selected and no item has focus yet.
`label`	`LocalizedMessage`	—	Accessible name for the group (`role="group"`). Accessible name prop; use {@link ToggleGroupLabelProps} instead.
`loop`	`boolean`	—	Whether arrow keys wrap at the ends. Defaults to `true`.
`onBlur`	`FocusEventHandler<HTMLElement>`	—	Called once when focus leaves the whole group for somewhere outside it, such as the next field. It is not called when focus moves between items, so a form library validates on blur once per visit.
`onFocus`	`FocusEventHandler<HTMLElement>`	—	Called once when focus enters the group from outside it. It is not called when focus moves between items. Use it with `onBlur` to track whether the field was touched.
`onValueChange`	`((value: DisplayValue \| null, details: ChangeDetails<ChangeReason>) => void) \| ((value: DisplayValue[], details: ChangeDetails<ChangeReason>) => void)`	—	Called when the selection changes. `details.reason` is {@link ChangeReason.ItemPress } for pointer and Enter/Space activation on an item.
`orientation`	`ToggleGroupOrientation`	—	Main-axis layout. Defaults to {@link ToggleGroupOrientation.Horizontal}.
`ref`	`Ref<HTMLDivElement>`	—	Ref to the group element.
`size`	`ToggleGroupSize`	—	Item height; feeds each {@link Button } child `size`. Defaults to {@link ToggleGroupSize.Large}.
`title`	`LocalizedMessage`	—	Native tooltip; accessibility hint, not visible UI title text.
`type`	`ToggleGroupType`	—	Selection mode. Defaults to {@link ToggleGroupType.Single}. Multi-select mode.
`value`	`DisplayValue \| DisplayValue[] \| null`	—	Selected item id when controlled. Selected item ids when controlled.

Storybook

Interactive examples and edge cases for this component are in Storybook.

DefaultOpens in a new tab

ToggleGroupRoot props

Prop	Default	Description
`collapseUnselectedLabels`	`false`	Animates unselected items down to their icons. Every collapsible item must provide `icon` and `aria-label`.

ToggleGroupItem

Name	Type	Default	Description
`value`	`string`	`required`	Stable id for selection.
`disabled`	`boolean`	`false`	Disables one option.
`children`	`ReactNode`	`required`	Visible label.
`icon`	`Icon`	—	Leading icon; required for items that collapse under `collapseUnselectedLabels`.
`aria-label`	`LocalizedMessage`	—	Accessible name; required when the label collapses to an icon. Pass `formatMessage` output.

Default

Controlled

Sizes

Icons

Collapse unselected labels

Lead icon and text

ToggleGroup vs SegmentedControl

Toggle Group / Usage

Toggle Group / Accessibility

On this page

ToggleGroupRoot

Storybook

ToggleGroupRoot props

Collapse unselected labels

Lead icon and text

ToggleGroup vs SegmentedControl

Toggle group

API and Development

View SourceOpens in a new tab Submit IssueOpens in a new tab

ToggleGroupRoot

Name	Type	Default	Description
`aria-description`	`LocalizedMessage`	—	Extended description for assistive tech.
`aria-label`	`LocalizedMessage`	—	Accessible name when the visible label is insufficient.
`aria-labelledby`	`string`	—	Id of the element that names this group; use {@link ToggleGroupLabelledByProps} instead. Id of the element that names this group.
`aria-placeholder`	`LocalizedMessage`	—	Hint for an empty control.
`children`	`ReactNode`	—	Toggle parts. Each must be a {@link ToggleGroupItem }.
`className`	`string`	—	Optional module class from colocated CSS.
`collapseUnselectedLabels`	`boolean`	—	Collapses unselected items to their icon and animates the selected label open. Items need {@link ToggleGroupItemProps.icon} and `aria-label` or visible button copy.
`defaultValue`	`DisplayValue \| DisplayValue[] \| null`	—	Initial selected id when uncontrolled. Initial selected ids when uncontrolled.
`disabled`	`boolean`	—	Disables every item.
`fullSpan`	`boolean`	—	When true, items span the full width of the parent evenly.
`initialItemId`	`DisplayValue`	—	Item id that receives `tabIndex={0}` when nothing is selected and no item has focus yet.
`label`	`LocalizedMessage`	—	Accessible name for the group (`role="group"`). Accessible name prop; use {@link ToggleGroupLabelProps} instead.
`loop`	`boolean`	—	Whether arrow keys wrap at the ends. Defaults to `true`.
`onBlur`	`FocusEventHandler<HTMLElement>`	—	Called once when focus leaves the whole group for somewhere outside it, such as the next field. It is not called when focus moves between items, so a form library validates on blur once per visit.
`onFocus`	`FocusEventHandler<HTMLElement>`	—	Called once when focus enters the group from outside it. It is not called when focus moves between items. Use it with `onBlur` to track whether the field was touched.
`onValueChange`	`((value: DisplayValue \| null, details: ChangeDetails<ChangeReason>) => void) \| ((value: DisplayValue[], details: ChangeDetails<ChangeReason>) => void)`	—	Called when the selection changes. `details.reason` is {@link ChangeReason.ItemPress } for pointer and Enter/Space activation on an item.
`orientation`	`ToggleGroupOrientation`	—	Main-axis layout. Defaults to {@link ToggleGroupOrientation.Horizontal}.
`ref`	`Ref<HTMLDivElement>`	—	Ref to the group element.
`size`	`ToggleGroupSize`	—	Item height; feeds each {@link Button } child `size`. Defaults to {@link ToggleGroupSize.Large}.
`title`	`LocalizedMessage`	—	Native tooltip; accessibility hint, not visible UI title text.
`type`	`ToggleGroupType`	—	Selection mode. Defaults to {@link ToggleGroupType.Single}. Multi-select mode.
`value`	`DisplayValue \| DisplayValue[] \| null`	—	Selected item id when controlled. Selected item ids when controlled.

Storybook

Interactive examples and edge cases for this component are in Storybook.

DefaultOpens in a new tab

ToggleGroupRoot props

Prop	Default	Description
`collapseUnselectedLabels`	`false`	Animates unselected items down to their icons. Every collapsible item must provide `icon` and `aria-label`.

ToggleGroupItem

Name	Type	Default	Description
`value`	`string`	`required`	Stable id for selection.
`disabled`	`boolean`	`false`	Disables one option.
`children`	`ReactNode`	`required`	Visible label.
`icon`	`Icon`	—	Leading icon; required for items that collapse under `collapseUnselectedLabels`.
`aria-label`	`LocalizedMessage`	—	Accessible name; required when the label collapses to an icon. Pass `formatMessage` output.