Toggle group

Toggles in a row on one track, letting several be on at once (multiple) or one at a time.

ui.toggle-groupcomponents/ui/toggle-group.tsx

Use case

For the AI

Use it for related tool switches that sit together: bold, italic and underline above a note, or grid and list icons that change how a product catalogue is laid out. With multiple any number can be on; without it, pressing one turns the others off, and pressing the one that is on leaves none.

Use it when

Formatting switches that can combine (multiple)
Icon switches for how a list is laid out (grid or list)
Several filters that can be on together

Use something else when

A labelled choice where exactly one is always picked: Segmented control
A single on or off switch: Toggle
Several options in a form that are saved: Checkbox group

Examples

Several at once

One at a time

Code

Import

import { BoldIcon, ItalicIcon, UnderlineIcon } from "@/components/icons"
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"

Usage

<ToggleGroup multiple defaultValue={["bold"]}>
  <ToggleGroupItem value="bold" aria-label="Bold">
    <BoldIcon />
  </ToggleGroupItem>
  <ToggleGroupItem value="italic" aria-label="Italic">
    <ItalicIcon />
  </ToggleGroupItem>
  <ToggleGroupItem value="underline" aria-label="Underline">
    <UnderlineIcon />
  </ToggleGroupItem>
</ToggleGroup>

Rules

value and defaultValue are arrays of item values, even one at a time (defaultValue={["grid"]}).
Set variant and size on ToggleGroup: the items take them from the group.
Each icon-only ToggleGroupItem carries aria-label.
Without multiple, one at a time can end with none pressed; when that is not allowed, use a segmented control.