Toggle Group

Grouped toggle primitives with single and multiple selection state.

Features

Single or multiple group modes
Controlled or uncontrolled state
Roving tabindex
Wrap-around arrow navigation
data-active state
Headless primitives

Installation

npm install @ariaui/toggle-group

Examples

These playgrounds use @ariaui/toggle-group for segmented formatting controls, compact and large sizes, disabled state, and fill-width text groups. Roving focus moves between group items; use mode="single" or mode="multiple" on ToggleGroup.Root.

Icon rows use lucide-react; shared class strings live in toggleExampleTokens.ts.

Group outline

Segmented icon toggle group with collapsed outline borders.

Preview

No preview output yet.

live.tsxReady

Group default

Segmented icon toggle group with the default surface treatment.

Preview

No preview output yet.

live.tsxReady

Group small

Compact segmented icon group.

Preview

No preview output yet.

live.tsxReady

Group large

Larger segmented icon group using the same active-state tokens.

Preview

No preview output yet.

live.tsxReady

Group disabled

Disabled segmented group with every item removed from interaction.

Preview

No preview output yet.

live.tsxReady

Group fill outline

Fill-width text toggle group with shared outline borders.

Preview

No preview output yet.

live.tsxReady

Group fill default

Fill-width text toggle group using the default surface treatment.

Preview

No preview output yet.

live.tsxReady

Anatomy

tsx

import * as ToggleGroup from "@ariaui/toggle-group";

export default function Example() {
  return (
    <ToggleGroup.Root>
      <ToggleGroup.Item />
    </ToggleGroup.Root>
  );
}

API Reference

Root

State owner and wrapper for grouped toggles. Renders a `<div>` and forwards div props.

Prop	Type	Default
mode	'single' \| 'multiple'	'multiple'
value	string \| string[] \| null	—
defaultValue	string \| string[] \| null	null \| []
onValueChange	(value: string \| string[] \| null) => void	—
onActiveChange	(actives: boolean[]) => void	—

Item

Self-registering toggle button with roving focus. Renders a `<button>`.

Prop	Type	Default
value	string	internal id
isActive	boolean	false

Attribute	Values
data-active	'true' when active, 'false' when inactive

Keyboard

Shortcut	Action
`→`/`↓`	Move focus to the next enabled item. Wraps from last to first.
`←`/`↑`	Move focus to the previous enabled item. Wraps from first to last.
`Home`	Move focus to the first enabled item.
`End`	Move focus to the last enabled item.
`Enter`	Activate or toggle the focused item.
`Tab`	Move focus out of ToggleGroup to the next focusable element.
`Shift`+`Tab`	Move focus out of ToggleGroup to the previous focusable element.

Accessibility

ToggleGroup follows the WAI-ARIA APG roving tabindex pattern so the group presents as a single tab stop:

Only one ToggleGroup.Item in a group holds tabIndex={0} at a time. Arrow keys move roving focus; Tab leaves the group.
Navigation wraps circularly and skips items marked isDisabled.
Item visual state is exposed via data-active.
Use Toggle.Root for one independent pressed button and ToggleGroup when related toggles share single or multiple selection state.