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`	—