ButtonGroup
Visually joins a set of related buttons into a single segmented control
Category: inputs · WCAG 2.2-AA · action, segmented, toolbar, layout
Sizes
- sm
- md
- lg
States
- idle
Props
| Prop | Type | Default | Description |
|---|---|---|---|
orientation | 'horizontal' | 'vertical' | horizontal | Layout orientation of the component. |
size | 'sm' | 'md' | 'lg' | md | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
roving | boolean | false | When true, uses roving tabindex so arrow keys move focus between buttons. |
loop | boolean | false | When true, navigation wraps around from end to start. |
aria-label | string | — | Accessible label used when no visible label is present. |
aria-labelledby | string | — | Id of the element that labels this component. |
Design tokens
--cascivo-button-radius--cascivo-radius-control
When to use
- Presenting several related, independent actions that read as one control (e.g. an editor toolbar)
- Visually grouping buttons that share context without implying mutual exclusivity
When not to use
- The buttons represent a single selected value among options — use ToggleGroup
- The actions are unrelated and should read as separate buttons — lay them out with spacing instead
How to build an accessible ButtonGroup in React →
Examples
Joined actions
<ButtonGroup aria-label="Text alignment"><Button>Left</Button><Button>Center</Button><Button>Right</Button></ButtonGroup>Vertical with roving focus
<ButtonGroup orientation="vertical" roving aria-label="View"><Button>List</Button><Button>Grid</Button></ButtonGroup>Related components
- ToggleGroup — Use when the buttons select a value rather than fire independent actions
- Button — A button group is a layout container for buttons