Toggle Group

A toggle group joins a set of Toggle buttons into one connected segmented control: a shared track with hairline dividers, where each pressed toggle fills to mark the selection. Use it for related on/off choices that share a slot, like text alignment or a view switcher, where one or several can be active at once.

Preview

Installation

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

Usage

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

<ToggleGroup>
  <ToggleGroupItem />
</ToggleGroup>

Composition

ToggleGroup
└── ToggleGroupItem

ToggleGroup wraps a row of ToggleGroupItems into one connected track, dividing them with hairlines and filling each pressed one to mark the selection. Each ToggleGroupItem is a Toggle that inherits the group's size and variant, and carries its own value.

Examples

With Icons

Use an icon as a ToggleGroupItem's content for a compact control. Give each icon-only item an aria-label.

Multiple

Add the multiple prop to let more than one toggle stay pressed at once. Each selected toggle fills independently.

Variants

Set variant to change the container chrome. Each pressed cell fills to mark the selection.

Sizes

Set size on the group to size every cell at once. Child ToggleGroupItems inherit it unless they set their own.

Detached

Set detached to split the buttons into standalone pills with gaps instead of one connected track.

Detached cells leave the shared track, so each one takes on its variant's own look: a filled plate for solid, a framed card for outline, or a bare button for ghost.

Without Separators

Set separators={false} to drop the hairline dividers between attached cells. (The outline variant divides cells with their collapsed borders instead, so it ignores this.)

Orientation

Set orientation="vertical" to stack the buttons. Dividers and cell sizing follow the axis.

Custom Selected Color

The selected cell is neutral by design. There's no accent prop; override it with utility classes when you want color. Note that --primary is light enough that it fails contrast as text on a tint, so the accent look pairs the tint with --info-foreground (the accessible brand-hue ink).

Disabled

Set disabled on the group to disable every cell at once, or on a single ToggleGroupItem to disable just that one.

API Reference

The ToggleGroup component is built on top of Base UI's ToggleGroup. All Base UI props are supported and passed through, including value, defaultValue, onValueChange, multiple, orientation, and disabled (see the Base UI ToggleGroup documentation). The custom props below are specific to our implementation.

Custom Props