Toggle Group

A set of two-state buttons that can be toggled on or off.

import { BoldIcon, ItalicIcon, UnderlineIcon } from "lucide-react"

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

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

Installation

pnpm dlx cubix@latest add toggle-group --base aria

Usage

Import

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

Example

<ToggleGroup>
  <ToggleGroupItem value="a">A</ToggleGroupItem>
  <ToggleGroupItem value="b">B</ToggleGroupItem>
  <ToggleGroupItem value="c">C</ToggleGroupItem>
</ToggleGroup>

Composition

Use the following composition to build a ToggleGroup:

ToggleGroup
├── ToggleGroupItem
└── ToggleGroupItem

Outline

Use variant="outline" for an outline style.

<ToggleGroup variant="outline" defaultValue={["all"]}>
  <ToggleGroupItem value="all" aria-label="Toggle all">
    All
  </ToggleGroupItem>
  <ToggleGroupItem value="missed" aria-label="Toggle missed">
    Missed
  </ToggleGroupItem>
</ToggleGroup>

Size

Use the size prop to change the size of the toggle group.

<ToggleGroup size="sm" defaultValue={["top"]} variant="outline">
  <ToggleGroupItem value="top">Top</ToggleGroupItem>
  <ToggleGroupItem value="bottom">Bottom</ToggleGroupItem>
  <ToggleGroupItem value="left">Left</ToggleGroupItem>
  <ToggleGroupItem value="right">Right</ToggleGroupItem>
</ToggleGroup>

Spacing

Use spacing to control the gap between items. Default is 2. Use spacing=0 for connected items.

<ToggleGroup
  size="sm"
  defaultValue={["top"]}
  variant="outline"
  spacing={0}
>
  <ToggleGroupItem value="top">Top</ToggleGroupItem>
  <ToggleGroupItem value="bottom">Bottom</ToggleGroupItem>
  <ToggleGroupItem value="left">Left</ToggleGroupItem>
  <ToggleGroupItem value="right">Right</ToggleGroupItem>
</ToggleGroup>

Vertical

Use orientation="vertical" for vertical toggle groups.

<ToggleGroup
  multiple
  orientation="vertical"
  spacing={1}
  defaultValue={["bold", "italic"]}
>
  <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>

Disabled

<ToggleGroup disabled>
  <ToggleGroupItem value="bold" aria-label="Toggle bold">
    <BoldIcon />
  </ToggleGroupItem>
  <ToggleGroupItem value="italic" aria-label="Toggle italic">
    <ItalicIcon />
  </ToggleGroupItem>
  <ToggleGroupItem value="strikethrough" aria-label="Toggle strikethrough">
    <UnderlineIcon />
  </ToggleGroupItem>
</ToggleGroup>

Custom

A custom toggle group example.

<Field>
  <FieldLabel>Font Weight</FieldLabel>
  <ToggleGroup
    value={[fontWeight]}
    onValueChange={(value) => {
      if (value[0]) setFontWeight(value[0])
    }}
    variant="outline"
    spacing={2}
    size="lg"
  >
    <ToggleGroupItem value="light" className="flex size-16 flex-col ...">
      <span className="text-2xl font-light">Aa</span>
      <span className="text-xs text-muted-foreground">Light</span>
    </ToggleGroupItem>
    {/* more items */}
  </ToggleGroup>
  <FieldDescription>
    Use <code>font-{fontWeight}</code> to set the font weight.
  </FieldDescription>
</Field>

RTL

Wrap the group in a container with dir="rtl" to mirror direction.

<div dir="rtl">
  <ToggleGroup variant="outline" defaultValue={["list"]}>
    <ToggleGroupItem value="list">List</ToggleGroupItem>
    <ToggleGroupItem value="grid">Grid</ToggleGroupItem>
    <ToggleGroupItem value="cards">Cards</ToggleGroupItem>
  </ToggleGroup>
</div>

API Reference

See also the Base UI Toggle Group documentation for primitive props.

ToggleGroup

Prop	Type	Default	Description
variant	"default" \| "outline"	"default"	Visual style applied to all items unless overridden.
size	"default" \| "sm" \| "lg"	"default"	Size applied to all items unless overridden.
spacing	number	2	Gap between items. Use 0 for connected items with shared borders.
orientation	"horizontal" \| "vertical"	"horizontal"	Layout orientation of the group.
multiple	boolean	false	When true, more than one item can be pressed (Base UI). Radix uses type="multiple".
value	string[]	-	Controlled pressed values.
defaultValue	string[]	-	Uncontrolled initial pressed values.
onValueChange	(value: string[]) => void	-	Called when the pressed values change.
disabled	boolean	false	When true, interaction is disabled for the group.
className	string	-	Additional Tailwind classes merged with the component styles (last one wins).

ToggleGroupItem

Prop	Type	Default	Description
value	string	-	Unique value for this item within the group.
variant	"default" \| "outline"	-	Overrides the group variant for this item.
size	"default" \| "sm" \| "lg"	-	Overrides the group size for this item.
disabled	boolean	false	When true, this item cannot be pressed.
className	string	-	Additional Tailwind classes merged with the component styles (last one wins).