# Toggle group

> A row of toggle buttons for one choice (alignment) or several (bold, italic), with a sliding pill.

Component · Pro · https://lodeui.com/components/toggle-group

## 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

```bash
npx shadcn@latest add @lode/toggle-group
```

Pro: needs a Lode API key and the `@lode` registry in components.json. See https://lodeui.com/docs/cli.

npm dependencies: motion

## Usage

```tsx title="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 |
| ← / → | Move between buttons |
| Home / End | First or last button |
| Enter / Space | 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.

## Related

- [Segmented control](https://lodeui.com/components/segmented-control) — A compact single choice with a pill that slides to the selection.
- [Radio group](https://lodeui.com/components/radio-group) — Radios as a list or as choice cards, with arrow-key navigation.
- [Tabs](https://lodeui.com/components/tabs) — Underline or pill tabs with an indicator that glides between them.