Docs › Components › Toggle Group

Shadcn Toggle Group

The shadcn/ui Toggle Group is a set of related two-state buttons, styled with Tailwind CSS v4. Built on accessible primitives, it supports single or multiple selection and arrow-key navigation between items. Toggle groups power formatting and view toolbars across ShadcnStore app blocks.

Key features

• Single or multiple selection via the multiple prop (defaults to single selection).
• value and defaultValue are always arrays of selected item values.
• Variants (default, outline) and sizes (sm, default, lg) shared across items.
• spacing for a gap between individually-rounded items, and orientation="vertical" to stack them.
• Arrow-key navigation with a single tab stop; disabled on the group disables every item at once.
• Controlled or uncontrolled via value / defaultValue.

Installation

npx shadcn@latest add toggle-group

Usage

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

export function Example() {
  return (
    <ToggleGroup multiple>
      <ToggleGroupItem value="bold" aria-label="Bold">
        <Bold />
      </ToggleGroupItem>
      <ToggleGroupItem value="italic" aria-label="Italic">
        <Italic />
      </ToggleGroupItem>
      <ToggleGroupItem value="underline" aria-label="Underline">
        <Underline />
      </ToggleGroupItem>
    </ToggleGroup>
  )
}

Single selection and variants

Omit multiple to allow only one item at a time, and set variant="outline" for bordered buttons. The top row is the default variant, the bottom is outline.

<ToggleGroup spacing={2} defaultValue={["center"]}>
  <ToggleGroupItem value="left">Left</ToggleGroupItem>
  <ToggleGroupItem value="center">Center</ToggleGroupItem>
  <ToggleGroupItem value="right">Right</ToggleGroupItem>
</ToggleGroup>

<ToggleGroup variant="outline" spacing={2} defaultValue={["center"]}>…</ToggleGroup>

Sizes

Set the size prop on ToggleGroup to size every item at once: sm or default.

<ToggleGroup size="sm" defaultValue={["top"]} variant="outline" spacing={2}>
  <ToggleGroupItem value="top">Top</ToggleGroupItem>
  <ToggleGroupItem value="bottom">Bottom</ToggleGroupItem>
  <ToggleGroupItem value="left">Left</ToggleGroupItem>
  <ToggleGroupItem value="right">Right</ToggleGroupItem>
</ToggleGroup>

Spacing

Set the spacing prop to control the gap between items; each item is individually rounded, matching the default look. Omit it (or pass 0) for a connected, fused-edge segmented control instead.

<ToggleGroup size="sm" variant="outline" spacing={2} defaultValue={["top"]}>
  <ToggleGroupItem value="top">Top</ToggleGroupItem>
  <ToggleGroupItem value="bottom">Bottom</ToggleGroupItem>
  <ToggleGroupItem value="left">Left</ToggleGroupItem>
  <ToggleGroupItem value="right">Right</ToggleGroupItem>
</ToggleGroup>

Vertical

Set orientation="vertical" to stack items in a column; arrow-key navigation follows the same axis.

<ToggleGroup multiple orientation="vertical" spacing={1} defaultValue={["bold", "italic"]}>
  <ToggleGroupItem value="bold" aria-label="Toggle bold"><Bold /></ToggleGroupItem>
  <ToggleGroupItem value="italic" aria-label="Toggle italic"><Italic /></ToggleGroupItem>
  <ToggleGroupItem value="underline" aria-label="Toggle underline"><Underline /></ToggleGroupItem>
</ToggleGroup>

Disabled

Set disabled on ToggleGroup to disable every item at once.

<ToggleGroup disabled multiple spacing={2}>
  <ToggleGroupItem value="bold" aria-label="Toggle bold"><Bold /></ToggleGroupItem>
  <ToggleGroupItem value="italic" aria-label="Toggle italic"><Italic /></ToggleGroupItem>
  <ToggleGroupItem value="underline" aria-label="Toggle underline"><Underline /></ToggleGroupItem>
</ToggleGroup>

Font weight selector

A real-world composition: pair a Toggle Group with Field to build a labeled, described control that reports its selection back into the surrounding form.

const [fontWeight, setFontWeight] = useState<string[]>(["normal"])

<Field>
  <FieldLabel>Font Weight</FieldLabel>
  <ToggleGroup value={fontWeight} onValueChange={setFontWeight} variant="outline" spacing={2} size="lg">
    <ToggleGroupItem value="light" className="flex size-16 flex-col items-center justify-center rounded-xl">
      <span className="text-2xl font-light">Aa</span>
      <span className="text-xs text-muted-foreground">Light</span>
    </ToggleGroupItem>
    {/* normal, medium, bold … */}
  </ToggleGroup>
  <FieldDescription>Use <code>font-{fontWeight[0] ?? "normal"}</code> to set the font weight.</FieldDescription>
</Field>

Accessibility

• Give icon-only items an aria-label describing each toggle.
• Arrow keys move between items; only one item is in the tab order.
• Omit multiple when the options are mutually exclusive, like text alignment.

When to use the Toggle Group

Use a Toggle Group for a small set of related on/off controls in a toolbar: text formatting, alignment, or a view switch. For a single toggle, use a Toggle. For an immediate setting, use a Switch; for form choices, a Radio Group.

Used in these blocks

• Apps: formatting and alignment toolbars.
• Datatables: view and density switches.
• Widgets: chart view toggles.

Related components

A Toggle Group coordinates several Toggles; for exclusive form choices use a Radio Group. Pair icon toggles with a Tooltip.

FAQ

What is the shadcn toggle group used for?

The Toggle Group is a set of related two-state buttons, such as text-alignment or formatting controls in a toolbar, with single or multiple selection.

How do I allow only one selected toggle?

Omit multiple on ToggleGroup so selecting one item deselects the others.

What is the difference between Toggle and Toggle Group?

Toggle is a single two-state button. Toggle Group coordinates several toggles with shared single or multiple selection.

How do I make items outlined?

Set variant="outline" on the ToggleGroup; items inherit the variant.