Toggle Group

Powered by

Base UIShadcn UIAnimate UI

Installation

When to use

Toggle Group operates as a segmented control, allowing users to filter or adjust the display of content within the current view. Unlike tabs that navigate between distinct content areas, segmented controls modify how existing content is presented. Content is typically shared across different segments, with the control determining what's visible or how it's formatted.

Use Toggle Group when:

• Filtering or adjusting a single content view
• Toggling between different presentations of the same data
• Content is shared across segments (list vs. grid, day vs. week vs. month)
• Making formatting choices (bold, italic, underline)
• The view context remains the same, just filtered or adjusted

Don't use Toggle Group when:

• Navigating between completely different content areas (use Tabs instead)
• Each option shows unique, non-overlapping content
• The interaction triggers a full content change rather than a filter/adjustment

Usage

<ToggleGroup>
  <ToggleGroupItem>A</ToggleGroupItem>
  <ToggleGroupItem>B</ToggleGroupItem>
  <ToggleGroupItem>C</ToggleGroupItem>
</ToggleGroup>

Interaction states

A segment is transparent at rest, so it takes the two archetypes from Interaction states according to whether it is the chosen one:

The hover is scoped to unselected segments, so the chosen one steps its own fill instead of taking a wash on top of it. Selection looks the same whether the group is single-select or multiple, and the transition is colour only — nothing moves, and it is dropped under prefers-reduced-motion.

Examples

Multiple

Outline Variant

The outline variant provides a bordered container around the toggle group, ideal for segmented controls that filter or adjust content.

Attached Mode

Vertical Orientation

Shifting Layout

Each segment paints its own selection, so a group whose surrounding layout resizes between selections has nothing to re-measure and nothing to chase — the selected segment is simply where it was.

Combined with Tabs

This example demonstrates the key difference between tabs (navigation) and toggle groups (filtering). Tabs navigate between different content areas, while toggle groups filter or adjust content within each tab's view.

Props

Registry Props

ToggleGroup

ToggleGroupItem

Keyboard interactions

Accessibility

• The container carries role="group" and each item is an aria-pressed toggle button (Base UI native semantics).
• Focus is roving — only one item is tabbable at a time, and arrow keys move focus between items.
• Provide an accessible group label — either aria-label on ToggleGroup or a visible heading with aria-labelledby — otherwise the purpose of the group isn't announced.
• Omit multiple for single-selection filters (like/dislike, sort direction) and pass multiple for independent switches (text formatting, feature flags). value/defaultValue are always arrays.

Credits

• We use Base UI for the toggle group component.
• We take our inspiration from Shadcn UI for the toggle group style.