Toggle Group
View in Storybook
Explore interactive examples and all component variations in our Storybook.
The ToggleGroup component provides a set of two-state buttons that can work together as a group. Built on Radix UI, it supports single or multiple selection modes with consistent styling and accessibility features. Perfect for toolbars, formatting controls, filter options, and any interface requiring grouped toggle functionality.
Basic Usage
Single Selection
Current alignment: left
Multiple Selection
Active formatting: bold
Different Variants
Default Variant
Outline Variant
Different Sizes
Small
Default
Large
Rich Text Editor Toolbar
Disabled State
Entire Group Disabled
Individual Items Disabled
Properties
ToggleGroup
| Property | Type | Description |
|---|---|---|
type | "single" | "multiple" | Selection mode - single allows one selection, multiple allows many. |
value | string | string[] | Controlled value(s) of the toggle group. |
defaultValue | string | string[] | Default value(s) when uncontrolled. |
onValueChange | (value: string | string[]) => void | Callback fired when selection changes. |
disabled | boolean | Whether the entire group is disabled. |
orientation | "horizontal" | "vertical" | Layout orientation of the group. |
dir | "ltr" | "rtl" | Reading direction for the group. |
loop | boolean | Whether keyboard navigation should loop. |
variant | "default" | "outline" | Visual variant applied to all items. |
size | "sm" | "default" | "lg" | Size variant applied to all items. |
className | string | Additional CSS classes for the group container. |
children | ReactNode | ToggleGroupItem components. |
ToggleGroupItem
| Property | Type | Description |
|---|---|---|
value | string | Unique value for this toggle item. |
disabled | boolean | Whether this specific item is disabled. |
variant | "default" | "outline" | Visual variant (overrides group variant). |
size | "sm" | "default" | "lg" | Size variant (overrides group size). |
className | string | Additional CSS classes for the item. |
children | ReactNode | Content of the toggle item. |
asChild | boolean | Render as child element instead of button. |
Accessibility
The ToggleGroup component includes comprehensive accessibility features:
- Keyboard Navigation - Arrow keys navigate between items, Space/Enter toggles
- Focus Management - Proper focus handling and visual indicators
- ARIA Support - Full ARIA attributes including roles and states
- Screen Reader Support - Toggle states announced to assistive technologies
- Group Semantics - Proper grouping and labeling for screen readers
- Disabled State - Proper handling of disabled items and groups
Common Use Cases
The ToggleGroup component is perfect for:
- Text Formatting - Bold, italic, underline controls in editors
- Alignment Controls - Left, center, right alignment options
- View Modes - List view, grid view, card view toggles
- Filter Options - Category filters and search refinements
- Settings Panels - Multiple option selections in preferences
- Toolbar Controls - Action buttons in application toolbars
- Layout Options - Different layout and display configurations
Best Practices
- Clear Labels - Use descriptive labels or icons with proper ARIA labels
- Logical Grouping - Group related options together
- Consistent Sizing - Use consistent sizes within the same interface
- Visual Feedback - Ensure clear visual indication of selected states
- Keyboard Support - Test keyboard navigation and shortcuts
- Icon Usage - Use recognizable icons with text labels when possible
- State Management - Handle controlled vs uncontrolled state appropriately
- Responsive Design - Consider mobile layouts and touch targets