Toggle Group
Forms
Actions
A set of two-state buttons that can be toggled on or off. Perfect for toolbars and option groups.
Toggle Group vs. Tabs vs. Segmented Control
Use Toggle Group for toolbar-style two-state buttons — bold/italic/underline, text alignment, view toggles. Supports single or multi-select mode.
- Tabs — section navigation with content panels swapping below
- Segmented Control — single-select view-mode switcher with animated indicator (List/Grid)
Preview
Single selection toggle group for alignment
Variants
Toggle Group comes in two visual variants
Default
Outline
Single Selection
Only one item can be active at a time
Selected: left
Multiple Selection
Multiple items can be active simultaneously
Selected: bold
Sizes
Three size options: small, medium, and large
Small
Medium (default)
Large
Props
ToggleGroup component API reference
| Prop | Type | Default | Description |
|---|---|---|---|
type | 'single' | 'multiple' | — | Selection mode (required) |
variant | 'default' | 'outline' | 'default' | Visual variant |
size | 'sm' | 'md' | 'lg' | 'md' | Toggle size |
value | string | string[] | — | Controlled value |
defaultValue | string | string[] | — | Default value (uncontrolled) |
onValueChange | (value: string | string[]) => void | — | Callback when value changes |
disabled | boolean | false | Disable all toggles |
ToggleGroupItem Props
| Prop | Type | Default | Description |
|---|---|---|---|
value | string | — | Unique value for this item (required) |
disabled | boolean | false | Disable this toggle item |
Usage
Import and implementation example
import { ToggleGroup, ToggleGroupItem } from '@/components/ui/toggle-group'import { Bold, Italic, Underline } from 'lucide-react'
export default function Example() { const [value, setValue] = useState('bold') const [multiValue, setMultiValue] = useState(['bold'])
return ( <> {/* Single selection */} <ToggleGroup type="single" defaultValue="left"> <ToggleGroupItem value="left">Left</ToggleGroupItem> <ToggleGroupItem value="center">Center</ToggleGroupItem> <ToggleGroupItem value="right">Right</ToggleGroupItem> </ToggleGroup>
{/* Multiple selection */} <ToggleGroup type="multiple" defaultValue={['bold']}> <ToggleGroupItem value="bold"> <Bold className="h-4 w-4" /> </ToggleGroupItem> <ToggleGroupItem value="italic"> <Italic className="h-4 w-4" /> </ToggleGroupItem> </ToggleGroup>
{/* Controlled state */} <ToggleGroup type="single" value={value} onValueChange={setValue} > <ToggleGroupItem value="bold">Bold</ToggleGroupItem> <ToggleGroupItem value="italic">Italic</ToggleGroupItem> </ToggleGroup>
{/* Variants */} <ToggleGroup type="single" variant="default">...</ToggleGroup> <ToggleGroup type="single" variant="outline">...</ToggleGroup>
{/* Sizes */} <ToggleGroup type="single" size="sm">...</ToggleGroup> <ToggleGroup type="single" size="md">...</ToggleGroup> <ToggleGroup type="single" size="lg">...</ToggleGroup> </> )}Features
Built-in functionality
- Single & multiple selection: Choose one or multiple items
- Two variants: Default and outline styles
- Three sizes: Small, medium, and large
- Controlled & uncontrolled: Flexible state management
- Icon + text support: Combine icons with labels
- Radix UI primitives: Built on accessible components
- Keyboard navigation: Full keyboard support
- Dark mode: Full dark mode support
Accessibility
Accessibility considerations
ARIA Attributes
Uses role="group" for the containerEach toggle uses aria-pressedProper focus management via RadixKeyboard Navigation
| Key | Action |
|---|---|
| Tab | Focus the toggle group |
| Arrow Keys | Navigate between toggles |
| Space | Toggle selected item |
| Enter | Toggle selected item |
Notes
- Group items are roving focus managed
- Visual indication of selected state
- Consider adding aria-label to icon-only groups
- Disabled items are skipped in navigation