How to build an accessible ToggleGroup in React

Single mode renders role="radiogroup" with role="radio" + aria-checked items; multiple mode uses a plain group of buttons with aria-pressed. Roving tabindex makes the set one tab stop and arrow keys move between items, matching the APG radiogroup/toolbar patterns

When to use a ToggleGroup

• Choosing one value from a small, mutually exclusive set that should stay visible (type="single")
• Toggling several independent options in a compact segmented control (type="multiple")

When not to use it

• The options are independent actions, not a selection — use ButtonGroup
• There are many options or they need labels and descriptions — use Radio or Checkbox groups

Keyboard interactions

Role radiogroup, verified at WCAG 2.2-AA.

• ArrowRight
• ArrowLeft
• ArrowUp
• ArrowDown
• Home
• End
• Enter
• Space

Common mistakes

Avoid: <ToggleGroup type="single" items={items} onValueChange={save} />

Prefer: <ToggleGroup type="single" value={align} onValueChange={setAlign} items={items} />

Single-select used as a controlled value should be driven by value/onValueChange so the source of truth lives with the parent

Example

<ToggleGroup type="single" defaultValue="left" items={[{ value: "left", label: "Left" }, { value: "center", label: "Center" }, { value: "right", label: "Right" }]} />

See the full ToggleGroup reference →