Toggle Group for React Aria

Pressed buttons for formatting or alignment, one at a time or several together.

Use it in a toolbar, where a form control would look out of place. When every option needs a visible label and the answer is required, use a Radio Group. In React, React Aria makes the row a single tab stop, and the arrow keys move across the buttons.

Installation

Anatomy

useToggleGroup
└── ToggleGroupItem

Usage

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

const ToggleGroupDemo = () => (
  <ToggleGroup selectionMode="multiple" variant="outline">
    <ToggleGroupItem aria-label="Toggle bold" id="bold">
      <BoldIcon aria-hidden="true" className="size-4" />
    </ToggleGroupItem>
    <ToggleGroupItem aria-label="Toggle italic" id="italic">
      <ItalicIcon aria-hidden="true" className="size-4" />
    </ToggleGroupItem>
    <ToggleGroupItem aria-label="Toggle strikethrough" id="strikethrough">
      <UnderlineIcon aria-hidden="true" className="size-4" />
    </ToggleGroupItem>
  </ToggleGroup>
);

Accessibility

Demos

Outline

variant set to outline draws a border around the items, here All and Missed as a small filter. One of them is pressed, starting with All. The outline reads as a single control more clearly than the default style, which has no border. Use it when the group sits on a busy surface and the buttons need an edge to hold them together.

Sizes

size is set on the group, and every item follows. The first row is sm, the second is the default md, both with the same Top, Bottom, Left, and Right labels so the difference is only height and type. Use the small size in a toolbar that is already crowded. Keep the default when the toggles are a primary control and need a comfortable target.

Spacing

spacing is the gap between items, in the same units as a Tailwind spacing step. Here it is 2, which is also the default, so the four position labels sit apart as separate buttons. Set it to 0 when they should join into one segmented control with shared borders. A wider gap helps when each item is a distinct tool rather than a slice of one choice.

Vertical

orientation set to vertical stacks the formatting buttons, with spacing of 1 and bold plus italic already pressed. More than one can stay on, which suits text styles that combine. Use a column for a narrow tool palette beside a canvas. Up and down move between the items, and the row no longer competes with the text for horizontal space.

Disabled

disabled on the group turns every button off, and none of them start pressed. Clicks and keyboard activation do nothing, and the icons fade. Use it when formatting is unavailable, such as a read-only document, rather than hiding the tools and shifting the layout. To retire one action only, disable that item and leave the rest of the group working.

Font Weight Selector

Four tiles preview Light, Normal, Medium, and Bold, and the caption names the class for the pressed weight. The group is controlled at size lg, with a gap so the tiles do not touch. Clicking the pressed tile would clear the choice, so the handler falls back to Normal and one weight always stays on. Use tiles when the option is easier to see than to read.

Rtl

dir is rtl, and the labels are Arabic for list, grid, and cards, with list pressed. The first item sits at the start of the line, which is the right side, and the outline border follows. Set the direction on the group when this control lives in a right-to-left page, even if the rest of the app is not. The pressed state does not need its own mirroring.

FAQ

API Reference