Toggle Group

Actions

A group of toggles that share a pressed state.

A toggle group coordinates several toggles so exactly one (or, with multiple, several) can be pressed at once. Selection is exclusive by default.

npx shadcn@latest add toggle-group

Single select

The default mode allows exactly one pressed item.

Preview

Live

tsx

1<ToggleGroup aria-label="Text alignment" defaultValue={["left"]}>
2  <ToggleGroupItem value="left" aria-label="Align left">
3    <AlignLeft />
4  </ToggleGroupItem>
5  <ToggleGroupItem value="center" aria-label="Align center">
6    <AlignCenter />
7  </ToggleGroupItem>
8  <ToggleGroupItem value="right" aria-label="Align right">
9    <AlignRight />
10  </ToggleGroupItem>
11</ToggleGroup>

Multiple

Add multiple to press several items at once.

Preview

Live

tsx

1<ToggleGroup multiple aria-label="Text formatting" defaultValue={["bold", "italic"]}>
2  <ToggleGroupItem value="bold" aria-label="Bold">
3    <Bold />
4  </ToggleGroupItem>
5  <ToggleGroupItem value="italic" aria-label="Italic">
6    <Italic />
7  </ToggleGroupItem>
8  <ToggleGroupItem value="underline" aria-label="Underline">
9    <Underline />
10  </ToggleGroupItem>
11</ToggleGroup>

API reference

All props of the underlying Base UI primitive are forwarded. The table below documents the Shelf-specific props.

Prop	Type	Description
defaultValue	string[]	Uncontrolled pressed values for the group.
value	readonly string[]	Controlled pressed values. Pairs with onValueChange.
onValueChange	(value: string[]) => void	Called with the pressed values whenever the group changes.
multiple	boolean= false	Allow several items pressed at once. When false, selection is exclusive.
orientation	"horizontal" \| "vertical"= "horizontal"	The orientation of the group.
disabled	boolean= false	Whether the group ignores user interaction.