---
type: doc
title: Toggle Group
description: A set of two-state buttons that can be toggled independently or as a single choice.
---

```astro live props={{ name: 'toggle-group' }}
---
import TextAlignCenterIcon from "@lucide/astro/icons/text-align-center"
import TextAlignEndIcon from "@lucide/astro/icons/text-align-end"
import TextAlignStartIcon from "@lucide/astro/icons/text-align-start"

import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"
---

<ToggleGroup
  defaultValue="center"
  variant="outline"
  spacing={0}
  aria-label="Text alignment"
>
  <ToggleGroupItem value="left" aria-label="Align left">
    <TextAlignStartIcon />
  </ToggleGroupItem>
  <ToggleGroupItem value="center" aria-label="Align center">
    <TextAlignCenterIcon />
  </ToggleGroupItem>
  <ToggleGroupItem value="right" aria-label="Align right">
    <TextAlignEndIcon />
  </ToggleGroupItem>
</ToggleGroup>
```

## Installation

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

## Usage

```astro
---
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"
---

<ToggleGroup defaultValue="center" aria-label="Text alignment">
  <ToggleGroupItem value="left">Left</ToggleGroupItem>
  <ToggleGroupItem value="center">Center</ToggleGroupItem>
  <ToggleGroupItem value="right">Right</ToggleGroupItem>
</ToggleGroup>
```

## Examples

### Multiple

Use `multiple` with an array or a space-separated string to select more than one item.

```astro live
---
import BoldIcon from "@lucide/astro/icons/bold"
import ItalicIcon from "@lucide/astro/icons/italic"
import UnderlineIcon from "@lucide/astro/icons/underline"

import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"
---

<ToggleGroup
  multiple
  defaultValue={["bold", "italic"]}
  aria-label="Text formatting"
>
  <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>
```

### Variants and Sizes

Set `variant` and `size` on the group to style every item. Set `spacing={0}` to join outlined items.

```astro live
---
import BoldIcon from "@lucide/astro/icons/bold"
import ItalicIcon from "@lucide/astro/icons/italic"
import UnderlineIcon from "@lucide/astro/icons/underline"

import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"
---

<div class="flex flex-col items-start gap-4">
  <ToggleGroup
    defaultValue="bold"
    size="sm"
    aria-label="Small formatting controls"
  >
    <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>
  <ToggleGroup
    defaultValue="italic"
    variant="outline"
    size="lg"
    spacing={0}
    aria-label="Large formatting controls"
  >
    <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>
</div>
```

### Vertical

The arrow keys follow the group orientation. `Home` and `End` move to the first and last enabled items.

```astro live
---
import ListIcon from "@lucide/astro/icons/list"
import ListOrderedIcon from "@lucide/astro/icons/list-ordered"
import ListTodoIcon from "@lucide/astro/icons/list-todo"

import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"
---

<ToggleGroup
  orientation="vertical"
  variant="outline"
  spacing={0}
  aria-label="List style"
>
  <ToggleGroupItem value="bulleted" aria-label="Bulleted list">
    <ListIcon />
  </ToggleGroupItem>
  <ToggleGroupItem value="numbered" aria-label="Numbered list">
    <ListOrderedIcon />
  </ToggleGroupItem>
  <ToggleGroupItem value="tasks" aria-label="Task list">
    <ListTodoIcon />
  </ToggleGroupItem>
</ToggleGroup>
```

### Disabled

Disable the whole group or a single item.

```astro live
---
import BoldIcon from "@lucide/astro/icons/bold"
import ItalicIcon from "@lucide/astro/icons/italic"
import UnderlineIcon from "@lucide/astro/icons/underline"

import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"
---

<div class="flex flex-wrap gap-4">
  <ToggleGroup
    disabled
    defaultValue="bold"
    aria-label="Disabled formatting controls"
  >
    <ToggleGroupItem value="bold" aria-label="Bold">
      <BoldIcon />
    </ToggleGroupItem>
    <ToggleGroupItem value="italic" aria-label="Italic">
      <ItalicIcon />
    </ToggleGroupItem>
  </ToggleGroup>
  <ToggleGroup
    defaultValue="bold"
    aria-label="Formatting controls with unavailable underline"
  >
    <ToggleGroupItem value="bold" aria-label="Bold">
      <BoldIcon />
    </ToggleGroupItem>
    <ToggleGroupItem value="italic" aria-label="Italic">
      <ItalicIcon />
    </ToggleGroupItem>
    <ToggleGroupItem value="underline" aria-label="Underline" disabled>
      <UnderlineIcon />
    </ToggleGroupItem>
  </ToggleGroup>
</div>
```

## API Reference

### ToggleGroup

| Prop           | Type                         | Default        | Description                                  |
| -------------- | ---------------------------- | -------------- | -------------------------------------------- |
| `defaultValue` | `string \| string[]`         | `[]`           | Initial selected value or values.            |
| `multiple`     | `boolean`                    | `false`        | Allows multiple selected items.              |
| `orientation`  | `"horizontal" \| "vertical"` | `"horizontal"` | Sets arrow-key navigation direction.         |
| `loop`         | `boolean`                    | `true`         | Wraps keyboard focus at either end.          |
| `disabled`     | `boolean`                    | `false`        | Blocks interaction for the whole group.      |
| `variant`      | `"default" \| "outline"`     | item default   | Applies a visual variant to every item.      |
| `size`         | `"sm" \| "default" \| "lg"`  | item default   | Applies a size to every item.                |
| `spacing`      | `number`                     | `2`            | Gap between items in Tailwind spacing units. |

### ToggleGroupItem

| Prop       | Type                        | Default     | Description                                   |
| ---------- | --------------------------- | ----------- | --------------------------------------------- |
| `value`    | `string`                    | required    | Unique value for the item.                    |
| `disabled` | `boolean`                   | `false`     | Disables the item.                            |
| `variant`  | `"default" \| "outline"`    | `"default"` | Item variant when the group does not set one. |
| `size`     | `"sm" \| "default" \| "lg"` | `"default"` | Item size when the group does not set one.    |

The root emits `toggle-group:change` with `{ value: string[] }`. Dispatch `toggle-group:set` with `{ value: string | string[] }` to update it from client code.

See the [GitHub source code](https://github.com/fulldotdev/ui/tree/main/src/components/ui/toggle-group) for the component source.
See the [data-slot docs](https://github.com/bejamas/data-slot/blob/main/packages/toggle-group/README.md) for controller methods and full keyboard behavior.