Toggle Group

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

View code

Features

Horizontal or vertical orientation
Can be controlled or uncontrolled
Full keyboard navigation

Anatomy

Root: The toggle group container component
Item: A toggle group item component

API Reference

createToggleGroup

Props

Prop	Default	Type / Description
`type`	`'single'`	`'single' \| 'multiple'` The type of toggle group. `single` allows a single item to be selected. `multiple` allows multiple items to be selected.
`disabled`	`false`	`boolean` Whether or not the toggle group is disabled.
`value`	`null`	`string \| string[] \| null` The value of the currently selected item. You can also pass an array of values to select multiple items if the toggle group is of type `multiple`.
`rovingFocus`	`true`	`boolean` Whether or not the toggle group should use roving focus.
`orientation`	`'horizontal'`	`'horizontal' \| 'vertical'` The orientation of the toggle group.
`loop`	`true`	`boolean` Whether or not the focus should loop back to the first item when the last item is reached.

Returned Props

Returned Prop	Type	Description
`options`	`Writable<CreateToggleGroupProps>`	A writable store with the options used to create the toggle group.
`value`	`Writable<string \| string[] \| null>`	A writable store with the value of the currently selected item.
`isPressed`	`Readable<(itemValue: string) => boolean>`	A derived store that takes an item value and returns whether or not the item is pressed.
`root`	-	The builder store used to create the toggle group root.
`item`	-	The builder store used to create toggle group items.

root

Data Attributes

Data Attribute	Value
`[data-orientation]`	`'vertical' \| 'horizontal'`
`[data-melt-toggle-group]`	Present on all toggle group elements.

item

Props

Prop	Default	Type / Description
`value` *	-	`string` The value of the item.
`disabled`	`false`	`boolean` Whether or not the item is disabled.

Data Attributes

Data Attribute	Value
`[data-orientation]`	`'vertical' \| 'horizontal'`
`[data-value]`	The value of the toggle item.
`[data-disabled]`	Present when the item is disabled.
`[data-state]`	`'on' \| 'off'`
`[data-melt-toggle-group-item]`	Present on all toggle group item elements.

Accessibility

Adheres to the Button WAI-ARIA design pattern

Key	Behavior
`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 in the group.
`End`	Moves focus to the last item in the group.

On This Page