Toggle Group

A set of toggle buttons that share variant and size styling. Built on Base UI's ToggleGroup primitive, it reuses the toggleVariants from the Toggle component and provides context so that individual items inherit the group's variant, size, and spacing.

import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"
import { BoldIcon, ItalicIcon, UnderlineIcon } from "lucide-react"

export default function ToggleGroupDemo() {
  return (
    <ToggleGroup>
      <ToggleGroupItem value="bold" aria-label="Toggle bold">
        <BoldIcon />
      </ToggleGroupItem>
      <ToggleGroupItem value="italic" aria-label="Toggle italic">
        <ItalicIcon />
      </ToggleGroupItem>
      <ToggleGroupItem value="underline" aria-label="Toggle underline">
        <UnderlineIcon />
      </ToggleGroupItem>
    </ToggleGroup>
  )
}

Anatomy

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

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

Examples

Default (no spacing)

Items render flush against each other with shared border handling.

<ToggleGroup variant="outline">
  <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>

With spacing

Set spacing to add a gap between items, giving each item its own rounded corners.

<ToggleGroup variant="outline" spacing={1}>
  <ToggleGroupItem value="left" aria-label="Align left">
    <AlignLeftIcon />
  </ToggleGroupItem>
  <ToggleGroupItem value="center" aria-label="Align center">
    <AlignCenterIcon />
  </ToggleGroupItem>
  <ToggleGroupItem value="right" aria-label="Align right">
    <AlignRightIcon />
  </ToggleGroupItem>
</ToggleGroup>

Vertical orientation

<ToggleGroup orientation="vertical" variant="outline">
  <ToggleGroupItem value="top" aria-label="Top">
    <ArrowUpIcon />
  </ToggleGroupItem>
  <ToggleGroupItem value="middle" aria-label="Middle">
    <MinusIcon />
  </ToggleGroupItem>
  <ToggleGroupItem value="bottom" aria-label="Bottom">
    <ArrowDownIcon />
  </ToggleGroupItem>
</ToggleGroup>

Small size

<ToggleGroup size="sm" variant="outline">
  <ToggleGroupItem value="bold" aria-label="Bold">
    <BoldIcon />
  </ToggleGroupItem>
  <ToggleGroupItem value="italic" aria-label="Italic">
    <ItalicIcon />
  </ToggleGroupItem>
</ToggleGroup>

API Reference

ToggleGroup

The root container. Provides variant, size, spacing, and orientation context to child items.

Prop	Type	Default	Description
`variant`	`"default" \| "outline"`	`"default"`	The visual variant applied to all items.
`size`	`"sm" \| "default" \| "lg"`	`"default"`	The size applied to all items.
`spacing`	`number`	`0`	Gap between items in spacing units. When `0`, items render flush with shared borders.
`orientation`	`"horizontal" \| "vertical"`	`"horizontal"`	The layout direction of the group.
`className`	`string`	—
`children`	`ReactNode`	—

Accepts all props from Base UI's ToggleGroup.

ToggleGroupItem

An individual toggle button within the group. Inherits variant and size from the group context, but can override them.

Prop	Type	Default	Description
`value`	`string`	—	The value for this item.
`variant`	`"default" \| "outline"`	`"default"`	Overrides the group variant for this item.
`size`	`"sm" \| "default" \| "lg"`	`"default"`	Overrides the group size for this item.
`disabled`	`boolean`	`false`	Whether the item is disabled.
`className`	`string`	—
`children`	`ReactNode`	—

Accepts all props from Base UI's Toggle.