Skip to main content

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

The builder function used to create the toggle group component.

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.
`loop`	`false`	`boolean` Whether or not the focus should loop back to the first item when the last item is reached.
`rovingFocus`	`true`	`boolean` Whether or not the toggle group should use roving focus.
`orientation`	`'horizontal'`	`'horizontal' \| 'vertical'` The orientation of the toggle group.
`defaultValue`	-	`string \| string[]` 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`.
`value`	-	`Writable<string \| string[] \| undefined>` A writable store that controls the value of the toggle group. If provided, this will override the value passed to `defaultValue`. See Bring Your Own Store
`onValueChange`	-	`ChangeFn<string \| string[] \| undefined>` A callback called when the value of the `value` store should be changed. This is useful for controlling the value of the toggle group from outside the toggle group. See Change Functions

Elements

Element	Description
`root`	The builder store used to create the toggle group root.
`item`	The builder store used to create toggle group items.

States

State	Description
`value`	A writable store that returns the value of the currently selected item.

Helpers

Helper	Description
`isPressed`	A derived store that takes an item value and returns whether or not the item is pressed.

Options

Option	Description
`type`	The type of toggle group. `single` allows a single item to be selected. `multiple` allows multiple items to be selected.
`disabled`	Whether or not the toggle group is disabled.
`loop`	Whether or not the focus should loop back to the first item when the last item is reached.
`rovingFocus`	Whether or not the toggle group should use roving focus.
`orientation`	The orientation of the toggle group.

root

The root toggle group element.

Data Attributes

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

item

The toggle group item element.

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.

Custom Events

Event	Value
`m-click`	`(e: ) => void`
`m-keydown`	`(e: ) => void`

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