Skip to main content

Toggle Group

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

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

The builder store used to create the toggle group root.

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.