# Toggle Group

A set of grouped toggle buttons.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available by appending `.md` to any URL or sending an `Accept: text/markdown` header. An agent skill is available at [/.well-known/agent-skills/site-skill.md](/.well-known/agent-skills/site-skill.md).

<ComponentPreview name="toggle-group" title="toggle-group.tsx">
<Component />
</ComponentPreview>

Toggle Group is a set of two-state toggle buttons rendered as native `<button>` elements. It supports `outline` and `default` variants, multiple selection, `sm` / `default` / `lg` sizes, `spacing`, and both horizontal and vertical orientation.

## Installation [#installation]

<CodeTabs>
<TabsList>
<TabsTrigger value="cli">
Command
</TabsTrigger>

<TabsTrigger value="manual">
Manual
</TabsTrigger>
</TabsList>

<TabsContent value="cli">
```bash
npx frakment add toggle-group
```

The CLI also installs the registry dependency: `toggle`.
</TabsContent>

<TabsContent value="manual">
<Steps>
<Step>
Install the following dependencies:
</Step>

```bash
npm install class-variance-authority
```

<Step>
Copy and paste the following code into your project.
</Step>

<ComponentSource name="toggle-group" title="components/ui/toggle-group.tsx" />

<Step>
Update the import paths to match your project setup.
</Step>
</Steps>
</TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx title="toggle-group.tsx"
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";
<DocsBaseSwitcher base="web" component="toggle-group" className="mb-6" />
```

```tsx
<ToggleGroup type="multiple" variant="outline">
  <ToggleGroupItem value="bold" aria-label="Toggle bold">
    <Bold />
  </ToggleGroupItem>
  <ToggleGroupItem value="italic" aria-label="Toggle italic">
    <Italic />
  </ToggleGroupItem>
</ToggleGroup>
```

## Composition [#composition]

```text
ToggleGroup
└── ToggleGroupItem
```

## Examples [#examples]

### Outline [#outline]

`variant="outline"` for bordered items with a shared rounded container.

<ComponentPreview name="toggle-group-outline" title="toggle-group-outline.tsx" src="examples/toggle-group-outline.tsx">
<a />
</ComponentPreview>

```tsx
<ToggleGroup variant="outline" defaultValue={["all"]}>
  <ToggleGroupItem value="all">All</ToggleGroupItem>
  <ToggleGroupItem value="missed">Missed</ToggleGroupItem>
</ToggleGroup>
```

### Sizes [#sizes]

`size` accepts `sm`, `default`, and `lg`.

<ComponentPreview name="toggle-group-sizes" title="toggle-group-sizes.tsx" src="examples/toggle-group-sizes.tsx">
<r />
</ComponentPreview>

```tsx
<ToggleGroup size="sm" variant="outline">...</ToggleGroup>
<ToggleGroup variant="outline">...</ToggleGroup>
```

### Spacing [#spacing]

`spacing` accepts a Tailwind spacing scale value (e.g. `2`) to separate items instead of merging them.

<ComponentPreview name="toggle-group-spacing" title="toggle-group-spacing.tsx" src="examples/toggle-group-spacing.tsx">
<l />
</ComponentPreview>

```tsx
<ToggleGroup size="sm" variant="outline" spacing={2}>
  ...
</ToggleGroup>
```

### Vertical [#vertical]

`orientation="vertical"` stacks items in a column — useful for toolbar-like selectors.

<ComponentPreview name="toggle-group-vertical" title="toggle-group-vertical.tsx" src="examples/toggle-group-vertical.tsx">
<c />
</ComponentPreview>

```tsx
<ToggleGroup type="multiple" orientation="vertical" spacing={1}>
  ...
</ToggleGroup>
```

### Disabled [#disabled]

Pass `disabled` on the group to lock every item.

<ComponentPreview name="toggle-group-disabled" title="toggle-group-disabled.tsx" src="examples/toggle-group-disabled.tsx">
<g />
</ComponentPreview>

```tsx
<ToggleGroup disabled>...</ToggleGroup>
```

### Font weight selector [#font-weight-selector]

Compose `ToggleGroup` with `Field` for a labeled, controlled selector — `value` / `onValueChange` accept a string array.

<ComponentPreview name="toggle-group-font-weight" title="toggle-group-font-weight.tsx" src="examples/toggle-group-font-weight.tsx" previewClassName="h-auto py-8">
<ToggleGroupFontWeightSelector />
</ComponentPreview>

```tsx
<Field>
  <FieldLabel>Font Weight</FieldLabel>
  <ToggleGroup value={[fontWeight]} onValueChange={(v) => setFontWeight(v[0])}>
    ...
  </ToggleGroup>
  <FieldDescription>Use font-{fontWeight} to set the weight.</FieldDescription>
</Field>
```

## In Context [#in-context]

### Text formatting [#text-formatting]

<ComponentPreview name="toggle-group-formatting" title="toggle-group-formatting.tsx" src="examples/toggle-group-formatting.tsx">
<ToggleGroupFormatting />
</ComponentPreview>

## API Reference [#api-reference]

All parts extend `React.ComponentProps<"div">` / `React.ComponentProps<"button">`.

### ToggleGroup [#togglegroup]

<PropsTable rows={[{"name":"variant","type":"\"default\" | \"outline\"","defaultValue":"\"default\"","description":"Visual style."},{"name":"size","type":"\"sm\" | \"default\" | \"lg\"","defaultValue":"\"default\"","description":"Item size."},{"name":"spacing","type":"number","defaultValue":"0","description":"Gap between items (Tailwind spacing scale)."},{"name":"orientation","type":"\"horizontal\" | \"vertical\"","defaultValue":"\"horizontal\"","description":"Layout direction."},{"name":"type","type":"\"single\" | \"multiple\"","defaultValue":"\"single\"","description":"Single-selection or multi-selection mode."},{"name":"value","type":"string | string[]","description":"Controlled selection. String in single mode, array in multiple mode."},{"name":"defaultValue","type":"string | string[]","description":"Initial selection when uncontrolled."},{"name":"onValueChange","type":"(value: string | string[]) => void","description":"Called when the selection changes."}]} />

### ToggleGroupItem [#togglegroupitem]

Requires `value` and an accessible `aria-label`.

## Controlled [#controlled]

```tsx
const [value, setValue] = React.useState(["bold"])
<ToggleGroup type="multiple" value={value} onValueChange={setValue}>{/* ... */}</ToggleGroup>
```

## Keyboard [#keyboard]

| Key | Action |
| :-- | :-- |
| `Tab` | Move focus to the group |
| `Space` / `Enter` | Toggle focused item |

## Data Attributes [#data-attributes]

| Attribute | Values |
| :-- | :-- |
| `data-slot` | `toggle-group`, `toggle-group-item` |
| `data-state` | `on` \| `off` |
| `data-orientation` | `horizontal` \| `vertical` |
| `data-disabled` | `true` |

## Variants [#variants]

| Variant | Use case |
| :-- | :-- |
| `default` | Solid pressed state |
| `outline` | Bordered |

## Accessibility [#accessibility]

- Each item renders a button with `aria-pressed`.
- `type="single"` (default) allows one active item, `type="multiple"` allows many.
- Provide `aria-label` when icon-only.

## Best Practices [#best-practices]

- **Group related toggles only.** Bold/Italic/Underline belong together; Save does not.
- **Use single type for exclusive choices.** Font family, alignment.
- **Use multiple type for independent toggles.** Formatting.
- **Cap at five items.** More become a toolbar with labels.
## Related Components [#related-components]

- [Toggle](/docs/components/web/toggle) — single toggle
- [Radio Group](/docs/components/web/radio-group) — mutually exclusive selection