Forms
ToggleGroup
A segmented control: several options, one strip.
When to reach for it
Examples
default
single — one of these
multiple — any of these
Notes
A segmented control: several options, one strip.
type="single" is a choice — Radix gives it radio semantics, and it is the right shape for a view switcher or a density setting. type="multiple" is a set of independent toggles, which is a different thing announced differently; choosing the wrong one is how a "filter by tag" control ends up telling a screen reader that picking one tag unpicks the others.
The two look different on purpose. A single-value strip moves ONE filled pill between its options, so the eye follows a thing travelling; a multiple-value strip fills each pressed option separately, because there is no single selection to travel. Two people looking at a screenshot should be able to tell which kind they are looking at, and before this they could not.
Distinct from Tabs, which switches PANELS and owns a tabpanel relationship. A toggle group changes a value.
Props
Also accepts everything in ComponentProps<typeof ToggleGroupPrimitive.Root>. Those are forwarded to the underlying element and are not listed row by row.
Parts
Composed at the call site rather than configured through props, so a layout this component did not anticipate is still expressible.
ToggleGroupItem
One segment.
In a single-value group the item draws no background of its own — the travelling pill behind it does — so it only changes ink. In a multiple-value group it fills, because there is nothing travelling.
Also accepts everything in ComponentProps<typeof ToggleGroupPrimitive.Item>. Those are forwarded to the underlying element and are not listed row by row.
Keyboard
| Key | Does |
|---|---|
| Tab | Moves into the strip — one stop for the group. |
| ←→ | Moves between segments. |
| EnterSpace | Toggles the focused segment. |
Accessibility
- type="single" gets radio semantics; type="multiple" gets independent toggles. Choosing wrong tells a screen reader that picking one option unpicks the others.