ToggleGroup

Grouped toggles with single or multiple selection and preserved semantics.

Installation

Run it from the root of a project already set up with zunoui init.

$ npx zunoui@latest add toggle-group

What add toggle-group installs alongside the component. The CLI skips any you already have in a compatible version.

4 examples · 1 component

Text alignment: one pressed item at a time.

multiple lets formatting options combine.

variant="outline" joins the items; text items read on their own.

orientation="vertical" stacks the items; up and down arrows move.

Keeps the props, events and refs of the matching Base UI primitive, plus ZUNO's styles.

Prop	Type	Default
`value / defaultValue` Pressed items, always an array (one item unless multiple).	`string[]`	—
`onValueChange` Called with the new pressed items.	`(value: string[]) => void`	—
`multiple` Lets several items be pressed at once.	`boolean`	`false`
`variant` outline joins the items into one segmented control.	`"default" \| "outline"`	`"default"`
`size` Applied to every item.	`"sm" \| "default" \| "lg"`	`"default"`
`orientation` Stacks the items and switches arrow keys to up/down.	`"horizontal" \| "vertical"`	`"horizontal"`
`ToggleGroupItem` One toggle; value is required.	`button`	—

The states that apply to this component and their visual treatment.

State	Treatment
Single	Pressing an item releases the previous one; it can be released to none.
Multiple	Items toggle independently.
Joined	variant="outline" shares borders; the focused item rises above its neighbours.
Disabled	On the group or on single items; disabled items are skipped by the arrow keys.

The group is one Tab stop: arrow keys move between items (roving focus) and Space or Enter presses the focused one.

Name the group with aria-label or aria-labelledby, and each icon-only item with its own aria-label.

Every item keeps aria-pressed, so assistive tech reports each state, in single and in multiple mode.

Use RadioGroup when a choice must always have exactly one answer in a form; ToggleGroup fits toolbars and view options.