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

npx shadcn@latest add @fulldev/toggle-group

Usage

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

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

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

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

---
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 for the component source. See the data-slot docs for controller methods and full keyboard behavior.

Sidebar

Search