Toggle Group

Choose one or more related options with toggle buttons.

Preview

Press the toggles above to change this text.

Design guidance

Use related two-state buttons for formatting or independent choices. Familiar symbols such as Bold, Italic and Underline need accessible names, without visible labels. Add text when a symbol's meaning needs explanation. Ghost and outline items retain their own boundaries and selected states.

Values remain arrays in both selection modes. A single-select group can become empty when the pressed item is selected again. If a task requires one choice at all times, enforce that rule in caller state. Use Tabs when the choice navigates between panels.

Installation

Install

npx shadcn@latest add https://ghost-ui.com/r/toggle-group.json

Reaction counter examples use optional @phosphor-icons/react regular/fill icons. Formatting examples use Lucide.

Basic usage

123456789import { Bold, Italic, Underline } from "lucide-react";
import { Toggle } from "@/components/ui/toggle";
import { ToggleGroup } from "@/components/ui/toggle-group";

<ToggleGroup aria-label="Text formatting" multiple defaultValue={["bold"]}>
  <Toggle value="bold" aria-label="Bold" icon={<Bold />} />
  <Toggle value="italic" aria-label="Italic" icon={<Italic />} />
  <Toggle value="underline" aria-label="Underline" icon={<Underline />} />
</ToggleGroup>

Structures

Examples

Multiple selection and outline

Set multiple to keep more than one item pressed. Outline keeps a boundary on each item.

Icons with text

Labels explain the search symbols. Familiar formatting icons remain unlabelled visually.

Icon alignment

Single selection still permits deselection.

Make the next step clear.

Counters

These four groups place counters right, bottom, left and top. Each example owns its reaction counts and selected values. The group supplies a presentation default; any item can override counterPosition.

Sizes

Each group's controls start at xs 24, sm 28, base 32 or lg 40px. Stacked counters grow to fit their content and padding. Group spacing stays independent of control size.

Vertical

Vertical groups keep icon items square.

Item overrides and wrappers

Defaults reach items through fragments and wrappers; explicit item props win.

Disabled item

Unavailable choices remain visible and do not change selection.

API reference

Toggle Group properties
Prop	Type	Default	Description
`value / defaultValue`	`string[]`	`[]`	Controlled or initial selected values, including in single mode.
`onValueChange`	`(values: string[], eventDetails) => void`	`—`	Existing Base UI event updates caller state after selection or deselection.
`multiple`	`boolean`	`false`	Allows independent pressed items.
`orientation / loopFocus`	`"horizontal" \| "vertical" / boolean`	`"horizontal" / true`	Base UI owns arrow-key navigation and looping.
`content / variant / size`	`Toggle presentation props`	`"icon" / "ghost" / "base"`	Defaults for descendants. Ghost/outline only; base is 32px. Explicit item values win through wrappers.
`counterPosition`	`"left" \| "right" \| "top" \| "bottom"`	`"right"`	Shared counter position; an explicit Toggle position wins. Counts and icon pairs belong to each item.
`disabled`	`boolean`	`false`	Disables the group; individual Toggle items can also be disabled.
`render / ref / className / style`	`Base UI ToggleGroup props`	`—`	Preserves caller root composition and state callbacks.

Behavior and advanced props follow Base UI Toggle Group.