Toggle Group

A compact single-selection control for switching between closely related options.

Use Toggle Group for two or three mutually exclusive choices such as grid or list view, sort direction, or content density. Use Tabs when each choice reveals a distinct panel.

Project view

Installation

$npx shadcn@latest add @patchui/toggle-group

The copied source is available in the registry JSON. The canonical implementation lives in packages/react/src/components/toggle-group.tsx.

Usage

<ToggleGroup value={view} onValueChange={setView} aria-label="Project view">
  <ToggleGroupItem value="grid" aria-label="Grid view">
    <SquaresFour />
  </ToggleGroupItem>
  <ToggleGroupItem value="list" aria-label="List view">
    <Rows />
  </ToggleGroupItem>
</ToggleGroup>

The group accepts a single string value. Each item needs a unique value, and the group needs an accessible name that describes what the selection controls.

Composition

ToggleGroup
└── ToggleGroupItem

Examples

Text labels

Prefer visible text when the choices cannot be represented by familiar icons.

Sort order

Sizes

Match the group to the height and density of adjacent controls.

Toggle group sizes

API reference

Prop	Type	Default	Description
value / onValueChange	string / (value: string) => void	-	Controls the selected item.
defaultValue	string	-	Sets the initial uncontrolled selection.
size	"sm" \| "md" \| "lg"	"md"	Matches the shared 24, 32, or 40 pixel control height.
ToggleGroupItem.value	string	-	Identifies an item within the group.

Toggle Group intentionally supports one selected value. Use Checkbox controls when people may select several independent options.

Keyboard behavior

Tab moves focus into the group.
Arrow keys move between enabled items.
Home and End move to the first and last enabled items.
Space activates the focused item.

Accessibility

Give the group an aria-label or aria-labelledby that names the choice.
Give every icon-only item its own aria-label.
Keep the selected option visually distinguishable without relying on icon color alone.
Avoid using more than a few choices in this compact control.