Toggle Group

Related two-state toggles with single or multiple selection, separators, and toolbar-aligned styling.

Installation

The components are exported from @by/experience-system. Add the package with your package manager:

pnpm add @by/experience-system

In this monorepo, depend on the workspace package (for example via workspace:* or your catalog) so imports resolve to packages/experience-system.

Composition

Use ToggleGroup as the root, ToggleGroupItem for each option, and optional ToggleGroupSeparator between items:

ToggleGroup
├── ToggleGroupItem
├── ToggleGroupSeparator (optional)
├── ToggleGroupItem
└── …

Each ToggleGroupItem must have a unique value. dir on the root defaults from ThemeProvider so keyboard and layout follow reading direction. See Radix Toggle Group.

Usage

import { ToggleGroup, ToggleGroupItem, ToggleGroupSeparator } from '@by/experience-system';

ToggleGroup and its parts are client components ('use client'). Use them inside a Client Component or a dynamic import when using the Next.js App Router.

<ToggleGroup type="multiple" defaultValue={['bold']} aria-label="Text style">
  <ToggleGroupItem value="bold" aria-label="Bold">
    B
  </ToggleGroupItem>
  <ToggleGroupSeparator />
  <ToggleGroupItem value="italic" aria-label="Italic">
    I
  </ToggleGroupItem>
</ToggleGroup>

Examples

Overview

type="multiple" with separators and variant="ghost" (same preview as at the top of the page).

Label with icon

segment="label" and variant="outline" for icon + text items.

Variants

outline and ghost groups side by side.

Outline

Ghost

Sizes

sm, md, and lg with variant="outline".

Small

Medium

Large

Vertical

orientation="vertical" with spacing={1} for outline and ghost.

Outline

Ghost

The tables below mirror the Radix UI Toggle Group API for Root and Item, plus Experience System extensions. dir on ToggleGroup follows ThemeProvider unless overridden.

ToggleGroup

Prop	Type	Default
`asChild`	`boolean`	`false`
`type`	`single` \| `multiple`	— (required)
`value`	`string` or `string[]`	—
`defaultValue`	`string` or `string[]`	—
`onValueChange`	`(value: string \| string[]) => void`	—
`disabled`	`boolean`	`false`
`rovingFocus`	`boolean`	`true`
`orientation`	`horizontal` \| `vertical`	—
`loop`	`boolean`	`true`
`dir`	`ltr` \| `rtl`	From `ThemeProvider` unless overridden
`variant`	`outline` \| `ghost`	`ghost`
`size`	`sm` \| `md` \| `lg` and legacy aliases (see `ToggleGroup` source)	`md`
`spacing`	`0` \| `1` \| `2` \| `3` \| `4`	`0`

Data attribute	Values
`data-slot`	`toggle-group`
`data-variant`	`outline` \| `ghost`
`data-size`	`sm` \| `md` \| `lg`
`data-spacing`	`0` \| `1` \| `2` \| `3` \| `4`
`data-orientation`	`horizontal` \| `vertical`

ToggleGroupItem

Prop	Type	Default
`asChild`	`boolean`	`false`
`value`	`string`	— (required)
`disabled`	`boolean`	—
`variant`	`outline` \| `ghost`	From group context
`size`	`sm` \| `md` \| `lg` and legacy aliases	From group context
`segment`	`icon` \| `label`	`icon`

Data attribute	Values
`data-slot`	`toggle-group-item`
`data-variant`	`outline` \| `ghost`
`data-size`	`sm` \| `md` \| `lg`
`data-segment`	`icon` \| `label`
`data-spacing`	mirrors group `spacing`
`data-state`	`on` \| `off`
`data-disabled`	Present when disabled
`data-orientation`	`horizontal` \| `vertical`

ToggleGroupSeparator

Renders a decorative Separator between items. orientation defaults to a bar across the group axis (vertical divider in a horizontal group, horizontal rule in a vertical group).

Prop	Type	Default
`orientation`	`horizontal` \| `vertical`	From group orientation
`className`	`string`	—

Also forwards Separator props except the Experience System replaces fixed orientation typing; see ToggleGroupSeparatorProps in the package.

Data attribute	Values
`data-slot`	`toggle-group-separator`

Accessibility

Use an aria-label (or aria-labelledby) on ToggleGroup; give each ToggleGroupItem a name (aria-label when the content is icon-only). Radix uses roving tabindex inside the group. See Radix Toggle Group — accessibility.

Keyboard interactions

Key	Description
`Tab`	Moves focus to the pressed item or the first item in the group.
`Space`	Toggles the focused item’s pressed state.
`Enter`	Toggles the focused item’s pressed state.
`ArrowRight` / `ArrowDown`	Moves focus to the next item (respects `orientation` and reading direction).
`ArrowLeft` / `ArrowUp`	Moves focus to the previous item.
`Home`	Moves focus to the first item.
`End`	Moves focus to the last item.

Source in the repo: packages/experience-system/src/components/ToggleGroup/ToggleGroup.tsx. Agent-oriented contracts: packages/experience-system/src/components/ToggleGroup/ToggleGroup.instructions.md.