build69
build69  /  Components  /  Selection & Choice  /  ToggleGroup

ToggleGroup

v1.0.5Updated 4 Oct 2026

Two-state toggle buttons built on Radix Toggle / ToggleGroup. Ships a standalone Toggle (aria-pressed) plus a ToggleGroup with single or multiple selection — ideal for view switchers, list-page status filters and formatt

View source← Back to catalog

Preview

Live · 14 stories
DefaultOpen ↗
▸Why this is recommendedtogglesegmentedfilterpressed+3

The default, out-of-the-box ToggleGroup.

Recommended for+14
  • ✓View-mode switchers (list / grid / table)
  • ✓Status filters on list pages
  • ✓Rich-text formatting toolbars
  • ✓Report period selectors (day / week / month)
Tags+6
togglesegmentedfilterpressedtoolbarradixdefault
Features+4
  • Standalone Toggle with aria-pressed (Space/Enter)
  • Group single or multiple selection
  • Controlled and uncontrolled (value / defaultValue / onValueChange)
  • Variants: default (joined outline segments) / soft (segmented control on muted track)
  • Sizes sm / default / lg
  • Six recipe tones for the pressed state, per-item tone overrides
  • Roving-tabindex arrow-key navigation, Home/End
  • Horizontal or vertical orientation
  • Icon-only items (aria-label required)
  • Labelled by FormField: the div role=group (not labelable) points at the field label with aria-labelledby; aria-required is dropped (not allowed on a group or its items)
Not recommended for−2
  • ✕Page navigation (use Tabs)
  • ✕On/off settings rows (use Switch)
  • ✕Exclusive form fields with labels/descriptions (use RadioGroup)

Install

Ask your agent, or call the MCP tool directly. The resolved bundle is written into your project.

get_registry_item({ name: "ToggleGroup" })

Usage

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

<ToggleGroup type="single" variant="soft" tone="primary" defaultValue="month" aria-label="Report period">
  <ToggleGroupItem value="week">Week</ToggleGroupItem>
  <ToggleGroupItem value="month">Month</ToggleGroupItem>
  <ToggleGroupItem value="year">Year</ToggleGroupItem>
</ToggleGroup>

Tick variants in the left menu — each adds a tab with that variant’s real story source, the same code the preview above renders.

Props

PropTypeRequired
type

Selection mode (ToggleGroup only)

'single' | 'multiple'yes
value

Controlled value(s)

string | string[]—
defaultValue

Uncontrolled initial value(s)

string | string[]—
onValueChange

Selection change callback

(value: string | string[]) => void—
variant

Joined outline segments or muted segmented control

'default' | 'soft'—
size

Item height (h-7 / h-8 / h-9)

'sm' | 'default' | 'lg'—
tone

Accent of the pressed state (shared recipe)

'neutral' | 'primary' | 'success' | 'warning' | 'danger' | 'info'—
orientation

Layout direction + arrow-key axis

'horizontal' | 'vertical'—
aria-labelledby

Id(s) of the element(s) that label the group; wins over a FormField label

string—
aria-label

Accessible name of the group; wins over a FormField label

string—

Every tonal component shares the same tone × emphasis API, so the pair looks identical across Button, Badge, Alert and more.

Related

Platform docsAll componentsSource files