Toggle Group

A set of toggle buttons: pick one, like text alignment, or turn on several, like bold and italic.

Stable

Web

iOS

Android

@advui/core

Source

Single choice

Preview

Code

Installation

Package

CLI (copy source)

pnpm

pnpm add @advui/core

npm

npm install @advui/core

Usage

import { ToggleGroup } from '@advui/core'

<ToggleGroup type="single" defaultValue="left" aria-label="Text alignment">
  <ToggleGroup.Item value="left" aria-label="Align left" icon={<AlignLeftIcon />} />
  <ToggleGroup.Item value="center" aria-label="Align center" icon={<AlignCenterIcon />} />
  <ToggleGroup.Item value="right" aria-label="Align right" icon={<AlignRightIcon />} />
</ToggleGroup>

Examples

Multiple and with labels

Formatting buttons that combine, and a view switcher with text.

Preview

Code

Style: bold

API reference

ToggleGroup

Prop	Type	Default	Description
`type` required	`'single' \| 'multiple'`	—	`single`: one choice at a time (it stays chosen when pressed again). `multiple`: any number on.
`value`	`string \| string[]`	—	The chosen item (`single`) or items (`multiple`), when you control them.
`defaultValue`	`string \| string[]`	—	Starting `value` when uncontrolled.
`onValueChange`	`(value) => void`	—	Called with a string (single) or an array (multiple).
`variant`	`'default' \| 'outline'`	`'default'`	Applies to every item.
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Applies to every item.
`orientation`	`'horizontal' \| 'vertical'`	`'horizontal'`	Layout direction.
`disabled`	`boolean`	`false`	Disables every item.
`aria-label`	`string`	—	Names the group for screen readers, e.g. “Text alignment”.

ToggleGroup.Item

Prop	Type	Default	Description
`value` required	`string`	—	Unique value.
`icon`	`ReactNode`	—	Icon before the label.
`disabled`	`boolean`	`false`	Not selectable.
`aria-label`	`string`	—	Required for icon-only items.

Accessibility

type="single" is a radiogroup of radio items with aria-checked, so screen readers say “1 of 3, selected”.
type="multiple" is a group of toggle buttons with aria-pressed.
Name the group with aria-label and every icon-only item with its own aria-label.
On iOS and Android items are radio buttons or toggle buttons with a checked state, and touch targets are at least 44pt.

Keyboard interactions
Key	Action
`Tab`	Moves focus into the group (to the chosen item) and out again.
`Arrow keys`	Move between items; in a single-choice group they also choose.
`Home / End`	First / last item.
`Space / Enter`	Turns the focused item on or off.

Responsive behavior

Items wrap to the next line when there is not enough room.

Platform notes

Web

One Tab stop for the whole group (roving tabindex).

iOS

VoiceOver reads each item as a radio button or toggle button.