Toggle Group

A set of two-state buttons that can be toggled on or off.

Anatomy

<ToggleGroup.Root>
  <ToggleGroup.Item />
</ToggleGroup.Root>

Examples

Controlled

Use the value and onValueChange props to control the toggle group state.

Root Provider

An alternative way to control the toggle group is to use the RootProvider component and the useToggleGroup hook. This way you can access the state and methods from outside the component.

Multiple

Demonstrates how to enable multiple selection within the group.

API Reference

Props

Root

Renders a <div> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`defaultValue`		`string[]` The initial selected value of the toggle group when rendered. Use when you don't need to control the selected value of the toggle group.
`deselectable`	`true`	`boolean` Whether the toggle group allows empty selection. Note: This is ignored if `multiple` is `true`.
`disabled`		`boolean` Whether the toggle is disabled.
`id`		`string` The unique identifier of the machine.
`ids`		`Partial<{ root: string; item: (value: string) => string }>` The ids of the elements in the toggle. Useful for composition.
`loopFocus`	`true`	`boolean` Whether to loop focus inside the toggle group.
`multiple`		`boolean` Whether to allow multiple toggles to be selected.
`onValueChange`		`(details: ValueChangeDetails) => void` Function to call when the toggle is clicked.
`orientation`	`'horizontal'`	`Orientation` The orientation of the toggle group.
`rovingFocus`	`true`	`boolean` Whether to use roving tab index to manage focus.
`value`		`string[]` The controlled selected value of the toggle group.

Attribute	Description
`[data-scope]`	toggle-group
`[data-part]`	root
`[data-disabled]`	Present when disabled
`[data-orientation]`	The orientation of the toggle-group
`[data-focus]`	Present when focused

Item

Renders a <button> element.

Prop	Default	Type
`value`		`string`
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`disabled`		`boolean`

Attribute	Description
`[data-scope]`	toggle-group
`[data-part]`	item
`[data-focus]`	Present when focused
`[data-disabled]`	Present when disabled
`[data-orientation]`	The orientation of the item
`[data-state]`	"on" \| "off"

RootProvider

Renders a <div> element.

Prop	Default	Type
`value`		`UseToggleGroupReturn`
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Context

API

Property	Type
`value`	`string[]` The value of the toggle group.
`setValue`	`(value: string[]) => void` Sets the value of the toggle group.
`getItemState`	`(props: ItemProps) => ItemState` Returns the state of the toggle item.

Accessibility

Keyboard Support

Key	Description
`Tab`	Moves focus to either the pressed item or the first item in the group.
`Space`	Activates/deactivates the item.
`Enter`	Activates/deactivates the item.
`ArrowDown`	Moves focus to the next item in the group.
`ArrowRight`	Moves focus to the next item in the group.
`ArrowUp`	Moves focus to the previous item in the group.
`ArrowLeft`	Moves focus to the previous item in the group.
`Home`	Moves focus to the first item.
`End`	Moves focus to the last item.