Toggle Group primitive

Headless Toggle Group: the behavior, keyboard support and ARIA of the WAI-ARIA toggle buttons pattern, with no styles.

@ndop/primitives/toggle-group
WAI-ARIA: toggle buttons

Import

Primitives ship in the @ndop/primitives package and have no styles. Their state is on data attributes for you to style. The styled Toggle Group is built on this one.

import {
  NdToggleGroup,
  NdToggleGroupItem,
} from '@ndop/primitives/toggle-group';

Accessibility

Implements the toggle buttons pattern of the WAI-ARIA Authoring Practices.

Keyboard

Keys the component handles.

Key	Action
`Tab`	Moves focus into the group, to its tab stop; then out of it.
`Space`or`Enter`	Presses or releases the focused item.
`ArrowRight`or`ArrowLeft`	Horizontal groups: moves focus to the next or previous enabled item, wrapping, without pressing it.
`ArrowDown`or`ArrowUp`	Vertical groups: moves focus to the next or previous enabled item, wrapping, without pressing it.
`Home`or`End`	Moves focus to the first or last enabled item.

Focus

Arrow keys, Home and End move focus only; pressing stays with Space and Enter. Disabled items are skipped.

Right-to-left

In right-to-left layouts, ArrowLeft moves to the next item and ArrowRight to the previous one. Direction comes from the nearest dir attribute, on the item or an ancestor.

API reference

NdToggleGroup

[ndToggleGroup]role groupfrom @ndop/primitives/toggle-group

Headless toggle group: a set of toggle buttons, button[ndToggleGroupItem], of which one (type="single") or any number (type="multiple") are pressed. Only one item is in the tab order; arrow keys move focus between items, wrapping, and Home and End jump to the ends. Its value is always an array of the pressed items' values. It's a ControlValueAccessor that every forms library binds (ADR-0004, amendments 1 and 4).

NdToggleGroup binding	Type	Default
`[defaultValue]` Initial `value` when it isn't bound.	`readonly string[]`	`[]`
`[type]` `single`: pressing an item releases the others. `multiple`: items are pressed independently.	`'single' \| 'multiple'`	`'single'`
`[orientation]` Which arrow keys move focus: left and right, or up and down.	`'vertical' \| 'horizontal'`	`'horizontal'`
`[disabled]` Disables every item. A disabled bound field does too.	`boolean`	`false`
`[(value)]` The pressed items' values, in both modes. Two-way bindable with `[(value)]`.	`readonly string[]`	`[]`

Data attribute	Values
`data-orientation`	—
`data-disabled`	—

NdToggleGroupItem

button[ndToggleGroupItem]from @ndop/primitives/toggle-group

One toggle button of a NdToggleGroup, on a native button. Give it a name that doesn't change with its state, such as aria-label="Bold".

Manages aria-pressed.

NdToggleGroupItem binding	Type	Default
`[value]`required The value this item adds to the group's while pressed.	`string`	`—`
`[disabled]` Disables this item; arrow keys skip it.	`boolean`	`false`

Data attribute	Values
`data-state`	—
`data-disabled`	—
`data-orientation`	—