Toggle Group

PreviewCopy Anchor Link

Single-select groups use joined outline buttons. This appearance picker starts at System and keeps one choice selected. The selection is local to the preview.

InstallationCopy Anchor Link

pnpm dlx shadcn@latest add https://migoy.stanleyaf.com/r/toggle-group.json

Installs Toggle Group and Toggle. Uses Base UI, the existing cn utility, and semantic theme tokens.

UsageCopy Anchor Link

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

Give each item a unique value. Use defaultValue to set the initial selection or value and onValueChange to control it. Both value props take arrays, including in single-selection mode.

Set size and variant on each item. Single-select groups default to joined outline items. With multiple, items use the default Toggle variant and an 8px gap.

An uncontrolled single-select group can be cleared by pressing the selected item again. For a setting that always needs a selection, use a controlled value and keep the current choice when the next value is empty.

CompositionCopy Anchor Link

ToggleGroup
├── ToggleGroupItem
└── ToggleGroupItem

Place items directly inside the group so their joined edges align. Keep item sizes consistent and give each item a distinct value.

Icon-only itemsCopy Anchor Link

Use familiar icons for compact view controls. Give each item a stable accessible name.

Multiple selectionCopy Anchor Link

Set multiple when each option can be pressed independently.

Keyboard and accessibilityCopy Anchor Link

• Label the group with aria-label or aria-labelledby. Give icon-only items a stable accessible name.
• Use Left and Right arrows to move focus, then Enter or Space to toggle the focused item. Set orientation="vertical" for a column that uses Up and Down arrows.
• Set disabled on an item or on the entire group to prevent interaction.
• Use Radio Group for a form choice that requires exactly one selection.

Based on shadcn Toggle Group and Base UI Toggle Group.