ToggleGroup
A set of toggle buttons for single or multiple selection
Category: inputs · WCAG 2.2-AA · selection, segmented, toolbar, choice
Variants
- single
- multiple
Sizes
- sm
- md
- lg
States
- on
- off
Props
| Prop | Type | Default | Description |
|---|---|---|---|
type | 'single' | 'multiple' | — | Whether one or multiple items can be pressed at once ('single' | 'multiple'). |
value | string | string[] | — | The controlled value. |
defaultValue | string | string[] | — | The initial value when uncontrolled. |
onValueChange | (value: string | string[]) => void | — | Called with the new value when it changes. |
items | { value: string; label?: string; icon?: React.ReactNode; disabled?: boolean }[] | — | The items to render. |
orientation | 'horizontal' | 'vertical' | horizontal | Layout orientation of the component. |
size | 'sm' | 'md' | 'lg' | md | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
disabled | boolean | false | When true, disables the control and removes it from the tab order. |
Design tokens
--cascivo-control-height-sm--cascivo-control-height-md--cascivo-control-height-lg--cascivo-radius-control--cascivo-radius-item--cascivo-color-bg-subtle--cascivo-color-surface--cascivo-color-text--cascivo-shadow-sm--cascivo-focus-ring
When to use
- Choosing one value from a small, mutually exclusive set that should stay visible (type="single")
- Toggling several independent options in a compact segmented control (type="multiple")
When not to use
- The options are independent actions, not a selection — use ButtonGroup
- There are many options or they need labels and descriptions — use Radio or Checkbox groups
How to build an accessible ToggleGroup in React →
Examples
Single selection
<ToggleGroup type="single" defaultValue="left" items={[{ value: "left", label: "Left" }, { value: "center", label: "Center" }, { value: "right", label: "Right" }]} />Multiple selection
<ToggleGroup type="multiple" defaultValue={["bold"]} items={[{ value: "bold", label: "Bold" }, { value: "italic", label: "Italic" }]} />Related components
- ButtonGroup — Use when the buttons fire independent actions rather than select a value
- Toggle — Use a single Toggle for one standalone binary option