Toggle Group

A set of toggles on one shell, with one or several pressed

Primitive

A toggle group sets related options on one shell, like text alignment or bold, italic, and underline. Pressed items sink into a deeper fill, whether one or several are on.

For actions rather than options, use ButtonGroup. For a single on/off control, use Toggle.

Installation

npxnpx shadcn@latest add @cubby-ui/toggle-group

Usage


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


<ToggleGroup>
  <ToggleGroupItem />
</ToggleGroup>

Composition

ToggleGroup
├── ToggleGroupItem
└── ToggleGroupSeparator

Give each ToggleGroupItem a value; the group reports the pressed values as an array.

Examples

Variants

Use variant to pick the shell the items sit on.

Variant	Description
`outline`	The default. An outline Button's fill and border.
`soft`	A secondary Button's fill.
`ghost`	No shell.

Size

Use size to match the group's height to a Button of the same size.

Set [--radius:9999px] on the group for a pill; the items' corners follow.

With Icons

Give each icon-only item an aria-label; a labelled item whose only child is an icon stays square.

Multiple

Set multiple to let several items stay pressed.

Separator

Use ToggleGroupSeparator to split items into clusters.

Always Selected

Pressing the selected item clears the group, so control the value and ignore an empty one to keep a selection.

Orientation

Set orientation="vertical" to stack the items; arrow keys follow the axis.

Custom Color

Set --toggle-group-selected-bg and --toggle-group-selected-fg on the group to recolor the fill.

Disabled

Set disabled on the group to turn off every item, or on one ToggleGroupItem.

Accessibility

Labels

Give the group an aria-label that names the choice ("Text alignment"), and every icon-only item its own.

Keyboard

Tab moves focus into the group; arrow keys move between items, and Space or Enter presses one. Set loopFocus={false} to stop at the ends.

Each item exposes its state with aria-pressed, and the label switches to full contrast when pressed, so the fill is never the only cue. In forced-colors mode the pressed item gets a Highlight border.

API Reference

The Toggle Group is built on top of Base UI's Toggle Group. All Base UI props are supported. The documentation below only covers custom props and modified defaults specific to our implementation.

For the complete Base UI API, see the Base UI Toggle Group documentation.

Props

ToggleGroup

The shell around the items. Wraps Base UI's ToggleGroup.

Notes

ToggleGroupItem

Wraps Toggle and takes its props except variant and size, which come from the group.

ToggleGroupSeparator

A line between items. Wraps Separator; its orientation defaults to perpendicular to the group. Arrow keys skip it.

Upgrading

If you're reinstalling over an earlier version, check these changes:

Before	Now
`variant="solid"`, a muted track, the default	`variant="outline"` is the default. `variant="soft"` is closest to the old track.
`detached` split items into separate toggles	Removed; items join in one shell. For standalone toggles, use separate `Toggle`s.
`separators` drew lines between every item	Place a `ToggleGroupSeparator` where you want one.
`ToggleGroupItem` took `variant` and `size`	Both come from the group.
Recolored with `--tgl-bg-selected` on items	Set `--toggle-group-selected-bg` and `--toggle-group-selected-fg` on the group.