Toggle Group

import {
  TextBIcon,
  TextItalicIcon,
  TextUnderlineIcon,
} from "@phosphor-icons/react"
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"

export default function ToggleGroupDemo() {
  return (
    <ToggleGroup
      spacing={2}
      orientation="horizontal"
      multiple
      defaultValue={["bold"]}
    >
      <ToggleGroupItem value="bold" aria-label="Toggle bold">
        <TextBIcon />
      </ToggleGroupItem>
      <ToggleGroupItem value="italic" aria-label="Toggle italic">
        <TextItalicIcon />
      </ToggleGroupItem>
      <ToggleGroupItem value="underline" aria-label="Toggle underline">
        <TextUnderlineIcon />
      </ToggleGroupItem>
    </ToggleGroup>
  )
}

ToggleGroup wraps the toggle group primitive of the chosen base and holds ToggleGroupItem buttons that share the group's variant and size. Items can be spaced apart, attached into one bar, or combined into a segmented control.

With spacing={0} and the default variant, the group becomes a segmented control: a filled track where a raised pill slides to the pressed item. Use a segmented group to switch between views, such as day, week and month. For a single on-off option, use Toggle; for switching panels of content, use Tabs.

Installation

CLI

$ pnpm dlx shadcn@latest add @esuiss/toggle-group

Works in any project with a components.json. See Installation for the one-line registry setup. Or use the suiss/ui CLI:

$ pnpm dlx @esuiss/ui@latest add toggle-group

Manual

1. Install the dependencies and add the cn helper:

$ pnpm add @base-ui/react class-variance-authority

2. Add the pieces it builds on: Toggle.

3. Copy the source into components/ui/toggle-group.tsx:

4. Update the import paths to match your project.

Usage

import { ToggleGroup, ToggleGroupItem } 

<ToggleGroup

The group's value is an array of item values. Use defaultValue for an uncontrolled group, or value with onValueChange to control it. Set multiple to let several items be pressed at once; without it, pressing an item releases the others.

Set variant and size on ToggleGroup; items take these from the group. Use spacing={0} with the outline variant to join items into one bordered bar.

Examples

Outline

Uses the outline variant with spaced items.

Attached

Joins outline items into one bar with spacing={0}.

Sizes

Compares the sm, default and lg sizes.

Segmented

Shows a single-choice segmented control with a sliding pill.

Segmented vertical

Stacks a segmented control vertically.

Segmented multiple

Uses a segmented control that allows several pressed items.

Segmented sizes

Compares segmented controls in each size.

Single selection

Allows only one pressed item in an outline group.

Vertical

Stacks attached outline items vertically.

Disabled

Disables every item in the group.

API Reference

Accessibility

• The group has the group role; name it with aria-label.
• Each item is a button with aria-pressed. Icon-only items need an aria-label.
• Arrow keys move focus between items: left and right in a horizontal group, up and down in a vertical one. Space toggles the focused item.
• disabled on the group disables every item.

Notes

• The segmented indicator appears only when exactly one item is pressed. Its position is set through --active-toggle-left, --active-toggle-top, --active-toggle-width and --active-toggle-height.
• variant and size set on a ToggleGroupItem are overridden by the group's values.
• The group sets data-variant, data-size, data-spacing and data-orientation; parts use the toggle-group, toggle-group-item and toggle-group-indicator slots.
• The segmented track uses bg-secondary and the pill uses bg-card. Its animation is removed when reduced motion is preferred.

ToggleGroup is built on the toggle group primitive and lays out ToggleGroupItem toggles in a row or a column. Items take the same variant and size styles as Toggle. The spacing prop sets the gap between items in steps of 4 points.

With spacing={0}, the group changes shape: the default variant becomes a segmented control on a bg-secondary track, and the outline variant joins items into one bordered strip. In a single-selection segmented control, the selected item is marked by a raised indicator that slides to the new item when the selection changes, like Tabs. In a multiple segmented control, each pressed item is raised on its own. Use the segmented style for switching views and the spaced style for toolbars.

Installation

$ pnpm dlx shadcn@latest add @esuiss-rn/toggle-group

$ pnpm dlx @esuiss/ui@latest add toggle-group

$ pnpm dlx @esuiss/ui@latest add toggle-group --platform swift