Toggle Group

A set of toggles with single or multiple selection.

Overview

ToggleGroup renders a role="group" of toggle buttons that share one value array. It selects a single item by default and any combination with multiple.

It reuses the Toggle styles, so install pulls in Toggle automatically. Items are native buttons with aria-pressed.

Preview

Customize

Variant
Size
Spacing
0
Orientation
Disabled

Installation

Add the component with the CLI. It copies the files in and installs anything they depend on.

npx vinyaas add toggle-group

Usage

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

export function Alignment() {
  return (
    <ToggleGroup aria-label="Text alignment" defaultValue={["left"]}>
      <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>
  );
}

Examples

Single selection

By default one item is pressed at a time, like a segmented control. Press the active item again to clear it.

Multiple selection

multiple lets any combination of items stay pressed.

Outline with text

The outline variant joins the items into one bordered bar. Text labels work like icons.

Sizes

sm, default, and lg match the Button height scale.

Spacing

spacing separates the items. Each one keeps its own rounded border.

Vertical

orientation=vertical stacks the items. Up and Down arrows move focus.

Disabled

disabled on the group or on a single item.

In practice

An editor toolbar pairs a multiple-selection style group with a single-selection alignment group.

API

Other attributes for the underlying element are passed through.

NameTypeDefaultDescription
multiplebooleanfalseToggleGroup. Allow several items pressed at once. By default one item is pressed at a time and pressing it again clears the group.
valuestring[]—ToggleGroup. Controlled pressed item values.
defaultValuestring[][]ToggleGroup. Initial pressed values for an uncontrolled group.
onValueChange(value: string[]) => void—ToggleGroup. Called with the next pressed values.
variant"default" | "outline""default"ToggleGroup. Applied to every item.
size"sm" | "default" | "lg""default"ToggleGroup. Applied to every item.
spacingnumber0ToggleGroup. Gap between items in 4px steps. 0 joins the items into one bar with shared borders.
orientation"horizontal" | "vertical""horizontal"ToggleGroup. Sets the layout direction and which arrow keys move focus.
disabledboolean—ToggleGroup disables every item. ToggleGroupItem disables one.
valuestring—ToggleGroupItem. Required. The value reported by the group.

Accessibility

The group is a role="group"; name it with aria-label or aria-labelledby. Each item reports aria-pressed.

  • Every item stays in the Tab order. Arrow keys, Home, and End also move focus between enabled items.
  • Space and Enter toggle the focused item.
  • Name icon-only items with aria-label.
  • Disabled items are skipped by arrow-key movement.