Skip to content
General

Toggle Group

A row of toggles that know about each other. One pressed at a time by default, which makes it the segmented control; set multiple and it becomes a set of independent switches sharing one geometry.

Sourcesrc/components/ui/toggle-group.tsx

Import

import {
  ToggleGroup,
  ToggleGroupItem,
} from "@mikenotthepope/substrateui"

Composition

variant and size travel from the group to its items through context, so a group never comes out with items of two different heights. Setting either on an item is possible but only worth it deliberately.

ToggleGroup
└── ToggleGroupItem

Several pressed at once

multiple makes the items independent — the right shape for text styling, where bold and italic are not alternatives. Without it the group behaves as one choice out of several.

Text items and sizes

Items take text as readily as icons. Where the labels are words, the group is often clearer than a Select — every option is visible and reachable in one press.

Controlled

value is an array in both modes — single-select is the array capped at one entry rather than a separate shape. Read value[0] for the single case.

Alignment: center

Direction

The group is a flex row, so in RTL the items reverse along with the rest of the line — the first item sits on the right. That is correct, and nothing needs configuring.

The icons are your own, and the alignment icons above are the case worth watching: AlignLeftmeans "align to the start of the line", which in RTL is the right. Name the values start and end rather than left and right, and mirror the glyph with rtl:-scale-x-100 so it points the way the text runs. See Direction (RTL).

Accessibility

The group is a single tab stop; arrow keys move between items inside it. That is what makes it a segmented control rather than three unrelated buttons, and it is why a row of loose Toggles is the wrong shape for a set of alternatives.

Each item is a button carrying aria-pressed. Icon-only items need an aria-label — every example above has one.

The group itself has no accessible name. Where the choice is not obvious from the surrounding text, give it an aria-labelsuch as "Text alignment".

API Reference

Built on Base UI's ToggleGroup and Toggle. The props below are the ones you reach for; see the Base UI toggle-group docs for the full inherited surface.

PropTypeDefaultDescription
variant"default" | "outline""default"Applied to every item through context, so you set it once on the group.
size"sm" | "default" | "lg""default"Applied to every item through context.
multiplebooleanfalseAllow several items pressed at once. Off, pressing one releases the last.
valuestring[]—The controlled list of pressed values — an array in both modes.
defaultValuestring[][]The items pressed on first render, when uncontrolled.
onValueChange(value: string[]) => void—Fired with the new list of pressed values.
disabledbooleanfalseDisable every item in the group.

ToggleGroupItem

PropTypeDefaultDescription
valuestring—Identifies the item in the group's value array. Required.
disabledbooleanfalseDisable this item only.