Toggle Group

A component for grouping multiple toggle switches, allowing users to switch between different options or states.

Anatomy

Usage

<script>
  import {ToggleGroup} from 'ui-ingredients';
  import {Bold01Icon, Italic01Icon, Underline01Icon} from '$lib/icons';

  /** @type {string[]} */
  let value = $state([]);
</script>

<ToggleGroup.Root
  {value}
  onValueChange={(detail) => {
    value = detail.value;
  }}
  multiple
>
  <ToggleGroup.Item value="1">
    <Bold01Icon />
  </ToggleGroup.Item>
  <ToggleGroup.Item value="2">
    <Underline01Icon />
  </ToggleGroup.Item>
  <ToggleGroup.Item value="3">
    <Italic01Icon />
  </ToggleGroup.Item>
</ToggleGroup.Root>

API Reference

Root

Prop	Default	Description
`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`		`{ 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.
`asChild`		`Snippet` Render a different element.

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

Item

Prop	Default	Description
`disabled`		`boolean` Whether the item is disabled.
`value`		`string` The value of the item.
`asChild`		`Snippet` Render a different element.

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

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.