Toggle Group
Grouped toggle buttons.
Usage
type is required and it is not a detail — it decides both the
behaviour and the shape of value. single gives you a string, multiple gives you
a string[]. Bits owns roving focus and arrow-key navigation, so the
whole group is one tab stop.
Multiple
In multiple mode any number of items can be active at once, and value is an array. Clicking an active item deselects it.
value: [bold]
Semantics per mode
The two modes expose different roles, and that is correct rather than an inconsistency. Picking one of a set is a radio group; independent on/off buttons are pressed buttons. Screen reader users hear the right thing in each case.
| Mode | Item role | State attribute |
|---|---|---|
single | radio | aria-checked |
multiple | button | aria-pressed |
Either way, the group needs a name — pass aria-label on the Root — and icon-only
items need one each.
Orientation
orientation="vertical" stacks the items and switches arrow-key navigation
to up/down.
Props
ToggleGroup.Root — plus type (required), disabled, loop, orientation and onValueChange forwarded to Bits.
| Prop | Type | Default |
|---|---|---|
type required `single` allows one active item; `multiple` allows many. Required, because it also decides the shape of `value`. | 'single' | 'multiple' | — |
value Active item(s). Bindable. `single` gives a string, `multiple` gives a string[] — the shape follows `type`. | string | string[] | — |
onValueChange Called when the active item(s) change. | (value: string & string[]) => void | — |
disabled Disables every item in the group. | boolean | — |
loop Keyboard focus loops from the last item back to the first. | boolean | — |
orientation Arrow-key navigation axis. | 'horizontal' | 'vertical' | — |
size | 'sm' | 'md' | 'lg' | 'md' |
class Extra classes merged onto the root. | string | — |
children Compose `ToggleGroup.Item` blocks inside. | Snippet | — |
ToggleGroup.Item — plus value (required) and disabled.
| Prop | Type | Default |
|---|---|---|
class Extra classes merged onto the item. | string | — |
child bits-ui | Snippet<[ToggleGroupItemSnippetProps & { props: Record<string, unknown>; }]> | undefined | — |
children bits-ui | Snippet<[ToggleGroupItemSnippetProps]> | undefined | — |
disabled bits-ui Whether the toggle item is disabled or not. | boolean | null | undefined | false |
id bits-ui | string | undefined | — |
ref bits-ui | HTMLElement | null | undefined | — |
value required bits-ui The value of the toggle item. | string | — |