Toggle Group

StableBase UI

Live preview

Installation

pnpm dlx shadcn@latest add @sc1m/toggle-group

This also merges the token layer and installs src/lib/cn.ts plus @base-ui/react. For the manual route — prerequisites, components.json, and app-level setup — see Installation.

Usage

import { ToggleGroup } from "@/components/ui/toggle-group";

Example

The preview above, with its source. This is the demo module verbatim, so the code and the thing it renders cannot drift apart.

<ToggleGroup aria-label="Text alignment">
  <Toggle value="left" aria-label="Align left">
    L
  </Toggle>
  <Toggle value="center" aria-label="Align center">
    C
  </Toggle>
  <Toggle value="right" aria-label="Align right">
    R
  </Toggle>
</ToggleGroup>

API reference

Each part forwards every prop of its Base UI counterpart; the tables list the ones declared on the part itself. See Base UI's reference for the inherited element props.

ToggleGroup

PropTypeDefaultDescription

valuereadonly Value[]—The pressed state of the toggle group represented by an array of the values of all pressed toggle buttons.

defaultValuereadonly Value[]—The pressed state of the toggle group represented by an array of the values of all pressed toggle buttons.

onValueChange((groupValue: Value[], eventDetails: ToggleGroup.ChangeEventDetails) => void)—Callback fired when the pressed states of the toggle group changes.

disabledbooleanfalseWhether the toggle group should ignore user interaction.

orientationOrientation'horizontal'

loopFocusbooleantrueWhether to loop keyboard focus back to the first item when the end of the list is reached while using the arrow keys.

multiplebooleanfalseWhen false only one item in the group can be pressed.

Accessibility

Behaviour, focus management, and ARIA wiring come from Base UI's Toggle Group — see its reference for the full keyboard map.

Disabled parts mute their contents rather than the element, keeping the focus ring at full strength where the part stays focusable.

Design tokens

The component reads semantic tokens only — no raw colour, radius, or duration appears in its source. Override the token, not the component.

TokenApplied to

--brand-radius-mdToggleGroup

--lineToggleGroup

--surface-raisedToggleGroup

Source

src/components/ui/toggle-group/toggle-group.tsx — no next/* imports, so it drops into any React 19 + Tailwind v4 app.

Toggle Group

On this page