Toggle Group

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

Installation

terminal

npx felicityui add toggle-group --platform react

Usage

example.tsx

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

<ToggleGroup type="single">
  <ToggleGroupItem value="a">A</ToggleGroupItem>
  <ToggleGroupItem value="b">B</ToggleGroupItem>
  <ToggleGroupItem value="c">C</ToggleGroupItem>
</ToggleGroup>

Composition

ToggleGroup
├── ToggleGroupItem
└── ToggleGroupItem

Default

Outline

variant="outline"

Size

sm | default | lg

Spacing

Default spacing is 2. Use spacing={0} for connected items.

Vertical

orientation="vertical"

Disabled

Custom

Font weight selector

Font weight

RTL

dir=rtl

API Reference

Prop	Type	Default	Description
type	single \| multiple	single	Single selects one value; multiple allows several.
value	string \| string[]	—	Controlled selected value(s).
defaultValue	string \| string[]	—	Uncontrolled initial value(s).
onValueChange	(value: string \| string[]) => void	—	Called when selection changes. Single returns string; multiple returns string[].
variant	default \| outline	default	Visual style applied to all items.
size	default \| sm \| lg	default	Control size for all items.
spacing	number	2	Gap between items (Tailwind spacing units). Use 0 for connected items.
orientation	horizontal \| vertical	horizontal	Layout direction.
disabled	boolean	—	Disables the entire group.
ToggleGroupItem.value	string	—	Item value used for selection.
className	string	—	Additional classes.

Accessibility

WCAG 2.2 AA

Group uses role=group; items expose aria-pressed.
Keyboard operable as native buttons.
Visible focus-visible ring.
Disabled group or item is not operable.

Platform notes

React

Native HTML with Felicity semantic tokens. Shares Toggle styles via toggleVariants — not Base UI / Radix runtime.

Client component (selection state).
Uses data-slot and data-state=on|off on items.
Default spacing is 2; use spacing={0} for connected items.
Icons use data-icon=inline-start|inline-end for placement.