Toggle Group

A set of two-state buttons that can be toggled on or off.

Powered by

Base UIShadcn UIAnimate UI

Installation

npx shadcn@latest add @redpanda/toggle-group

pnpm dlx shadcn@latest add @redpanda/toggle-group

yarn dlx shadcn@latest add @redpanda/toggle-group

bunx shadcn@latest add @redpanda/toggle-group

nubx shadcn@latest add @redpanda/toggle-group

aube dlx shadcn@latest add @redpanda/toggle-group

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 value="a">A</ToggleGroupItem>  <ToggleGroupItem value="b">B</ToggleGroupItem>  <ToggleGroupItem value="c">C</ToggleGroupItem></ToggleGroup>

Choices may come from fragments or a shared component, as the attached-mode example demonstrates. Keep their rendered buttons as direct DOM siblings of the group; attachment follows the actual first and last button, not the shape of the React children. An attached group with one choice rounds every corner.

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.