Segmented Controls

ToggleGroup is the segmented control: a row of buttons where either one option is active (type="single") or several can be active at once (type="multiple"). Each child is a ToggleGroupItem. It shares the variants of Toggle, and the group propagates variant and size to its items. Reach for it when there are a few always-visible options and you want them shown inline rather than hidden in a dropdown.

Live demo

The interactive story below runs from the deployed Storybook.

Usage

Source: toggle-group.tsx

import { ToggleGroup, ToggleGroupItem } from "@beacon/design-system";

// Single choice (mutually exclusive)
<ToggleGroup type="single" defaultValue="center">
  <ToggleGroupItem value="left" aria-label="Align left">Left</ToggleGroupItem>
  <ToggleGroupItem value="center" aria-label="Align center">Center</ToggleGroupItem>
  <ToggleGroupItem value="right" aria-label="Align right">Right</ToggleGroupItem>
</ToggleGroup>

// Multiple choices, outline variant set once on the group
<ToggleGroup type="multiple" variant="outline">
  <ToggleGroupItem value="bold" aria-label="Bold">B</ToggleGroupItem>
  <ToggleGroupItem value="italic" aria-label="Italic">I</ToggleGroupItem>
  <ToggleGroupItem value="underline" aria-label="Underline">U</ToggleGroupItem>
</ToggleGroup>

Parts

Part	Role
ToggleGroup	Root container. Sets type ("single" or "multiple"), the value, and shared variant / size for all items.
ToggleGroupItem	An individual segment. Requires a value. Inherits variant and size from the group via context.

Key props

Prop	On	Type	Description
type	ToggleGroup	"single" | "multiple"	Whether one or many items can be active.
value / defaultValue	ToggleGroup	string | string[]	Controlled / uncontrolled selection (string for single, array for multiple).
onValueChange	ToggleGroup	(value) => void	Fires when the selection changes.
variant	ToggleGroup / ToggleGroupItem	"default" | "outline"	Visual style; set on the group to apply to all items.
size	ToggleGroup / ToggleGroupItem	"default" | "sm" | "lg"	Control sizing; set on the group to apply to all items.
value	ToggleGroupItem	string	The value this segment represents.
disabled	both	boolean	Disable the whole group or a single item.

When to use

• A small set of mutually exclusive options that should stay visible (view mode, alignment, time range).
• A multi-select toolbar where several formatting states can be active together.
• Anywhere a dropdown would add an unnecessary click for two to five options.

Do not use a segmented control for a long list of options; that overflows the row, so use a Picker instead. For a single standalone on/off button, use Toggle.