Prepared Docs

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

ToggleGroupRoot

Name	Type	Default	Description
`className`	`string`	—	Additional CSS class name applied to the root container.
`collapseUnselectedLabels`	`boolean`	`false`	Collapses every unselected item down to its icon, animating the selected item's label open. Items must supply an `icon` and an `aria-label` so the collapsed items stay identifiable. Opt-in — same contract as `SegmentedControl`.
`defaultValue`	`string`	—	Default selected value for uncontrolled usage.
`disabled`	`boolean`	—	When true, disables all toggle items.
`fullSpan`	`boolean`	—	When true, items span the full width of the parent evenly.
`onValueChange`	`((value: string) => void)`	—	Callback fired when the selected toggle changes.
`ref`	`Ref<HTMLDivElement>`	—	Ref forwarded to the root `<div>` element.
`size`	`ToggleGroupSize`	`ToggleGroupSize.Large`	Size variant controlling height and padding.
`value`	`string`	—	Controlled selected value.

Storybook

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

Collapse Unselected Labels

Collapse Unselected Labels Small

Vs Segmented Control

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`	`SVGAsset`	—	Leading icon; required for items that collapse under `collapseUnselectedLabels`.
`aria-label`	`string`	—	Accessible name; required when the label collapses to an icon.

Default

Controlled

Sizes

Icons

Collapse unselected labels

Lead icon and text

ToggleGroup vs SegmentedControl

Toggle Group / Usage

Toggle Group / Accessibility

ToggleGroupRoot

Storybook

ToggleGroupRoot props

Collapse unselected labels

Lead icon and text

ToggleGroup vs SegmentedControl

View Source

Submit Issue

ToggleGroupRoot

Name	Type	Default	Description
`className`	`string`	—	Additional CSS class name applied to the root container.
`collapseUnselectedLabels`	`boolean`	`false`	Collapses every unselected item down to its icon, animating the selected item's label open. Items must supply an `icon` and an `aria-label` so the collapsed items stay identifiable. Opt-in — same contract as `SegmentedControl`.
`defaultValue`	`string`	—	Default selected value for uncontrolled usage.
`disabled`	`boolean`	—	When true, disables all toggle items.
`fullSpan`	`boolean`	—	When true, items span the full width of the parent evenly.
`onValueChange`	`((value: string) => void)`	—	Callback fired when the selected toggle changes.
`ref`	`Ref<HTMLDivElement>`	—	Ref forwarded to the root `<div>` element.
`size`	`ToggleGroupSize`	`ToggleGroupSize.Large`	Size variant controlling height and padding.
`value`	`string`	—	Controlled selected value.

Storybook

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

Collapse Unselected Labels

Collapse Unselected Labels Small

Vs Segmented Control

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`	`SVGAsset`	—	Leading icon; required for items that collapse under `collapseUnselectedLabels`.
`aria-label`	`string`	—	Accessible name; required when the label collapses to an icon.