ToggleGroup

ToggleGroup controls a set of Toggle.Root buttons. The group permits one selection or more than one selection. It has roving focus, it obeys the disabled state, and its value is an array.

Anatomy

ToggleGroup.Root contains ToggleGroup.Item buttons. That part is Toggle.Root under the namespace of the group, and the two names are the same component. Each button must have a unique value. The group uses the value to record the selection.

<script>
	import { ToggleGroup } from '@human-kit/ui';
</script>

<ToggleGroup.Root defaultValue={['bold']} selectionMode="multiple" aria-label="Text style">
	<ToggleGroup.Item value="bold">Bold</ToggleGroup.Item>
	<ToggleGroup.Item value="italic">Italic</ToggleGroup.Item>
</ToggleGroup.Root>

Single selection

selectionMode="single" is the default. It keeps one value selected, or none. The value stays an array. Add disallowEmptySelection when one enabled toggle must stay selected.

Vertical orientation

orientation="vertical" moves the roving focus to the Up arrow key and the Down arrow key. The keyboard focus does not stop on a disabled toggle.

Usage guidelines

  • Use value and defaultValue arrays for a single selection and for more than one selection.
  • Use selectionMode="single" when only one toggle can be selected.
  • Use selectionMode="multiple" when more than one toggle can be selected.
  • Use disallowEmptySelection when one enabled toggle must stay selected.
  • Each button in the group must have a unique value.
  • A toggle in a group ignores its own selected and defaultSelected props.

Accessibility

  • ToggleGroup.Root has role="group".
  • Give the group an accessible name with aria-label or aria-labelledby.
  • Each Toggle.Root stays a native toggle button with aria-pressed.
  • The arrow keys move the focus through the enabled toggles. The Home key and the End key move the focus to the first toggle and to the last toggle.

API reference

Root

The group container. It makes a div with role="group". It controls the selection across the Toggle.Root buttons in it, and it controls the roving focus.

Prop Type Default

* required. Native HTML attributes of the underlying element are also accepted.

Data attribute Description
data-disabled Present when the whole group is disabled.
data-multiple Present when `selectionMode` is "multiple".
data-orientation The group orientation ("horizontal" or "vertical").
data-toggle-group-root Identifies the group element.

Item

One button of the group. It is Toggle.Root under the namespace of the group, and the two names are the same component.

Prop Type Default

* required. Native HTML attributes of the underlying element are also accepted.

Data attribute Description
data-disabled Present when the toggle or its group is disabled.
data-focus-visible Present when the focus came from the keyboard.
data-focused Present when the toggle has the focus.
data-grouped
data-hovered Present while the pointer is over the toggle.
data-pressed Present while the toggle is held down.
data-selected Present when the toggle is selected.
data-toggle-root Identifies the toggle element.
data-unselected Present when the toggle is not selected.