Toggle groupPro
A row of toggle buttons for one choice (alignment) or several (bold, italic), with a sliding pill.
The quick brown fox jumps over the lazy dog.
When to use
- Formatting toolbars: bold / italic (many) or alignment (one).
- View switches with icons where a segmented control feels too heavy.
When not to use
- Form choices with descriptions: use a radio group.
- Navigation: use tabs.
Installation
Usage
Import it from @/components/ui/toggle-group after installing.
example.tsx
import { AlignCenter, AlignLeft, Bold, Italic } from "lucide-react";
import { ToggleGroup } from "@/components/ui/toggle-group";
<ToggleGroup aria-label="Alignment" defaultValue="left" items={[
{ value: "left", label: "Left", icon: <AlignLeft />, iconOnly: true },
{ value: "center", label: "Center", icon: <AlignCenter />, iconOnly: true },
]} />
<ToggleGroup aria-label="Style" type="multiple" defaultValue={["bold"]} items={[
{ value: "bold", label: "Bold", icon: <Bold />, iconOnly: true },
{ value: "italic", label: "Italic", icon: <Italic />, iconOnly: true },
]} />API reference
ToggleGroup
A group of toggle buttons. Single mode allows none or one; multiple mode any number.
| Prop | Type | Default | Description |
|---|---|---|---|
| items | readonly { value; label; icon?; iconOnly?; disabled? }[] | – | iconOnly hides the text but keeps it as the accessible name. |
| type | "single" | "multiple" | "single" | Changes value to T | null or T[]. |
| value / defaultValue / onValueChange | T | null / T[] | – | Controlled or uncontrolled. |
| size | "sm" | "md" | "md" | Button height. |
| aria-label | string | – | Required: names the group. |
Keyboard interactions
| Keys | Action |
|---|---|
| Tab | Move into and out of the group |
| ←or→ | Move between buttons |
| HomeorEnd | First or last button |
| EnterorSpace | Toggle |
Accessibility
- A labelled group of toggle buttons with aria-pressed.
- Icon-only buttons are named and show a tooltip.
Motion
- Single mode: the pill slides to the new choice. Multiple mode: each pill pops in.
Responsive behavior
- Hugs its content.
Performance
- Plain buttons; one animated pill.
Notes for AI
- Pass type="multiple" with an array value, or leave it single with a string.
This page as Markdown, for assistants and coding agents:
/components/toggle-group/markdownThe full library index for assistants is at /llms.txt.
Lode222 doc pagesllms.txt