Toggle Group
Single or multiple selection group of toggle buttons. Ideal for toolbars and alignment pickers.
Install
Import path
Examples
Disabled
A set of two-state buttons that can be toggled on or off.
Custom
A custom toggle group example.
Use font-normal to set the font weight.
Outline
Use variant='outline' for an outline style.
RTL
Right-to-left layout support for languages such as Arabic and Hebrew.
Translations are AI-generated for demonstration and may be imperfect.
Size
Use the size prop to change the size of the toggle group.
Spacing
Use spacing to add spacing between toggle group items.
Vertical
Use orientation='vertical' for vertical toggle groups.
Anatomy
How the parts compose. Copy this skeleton and fill in the slots.
import { ToggleGroup, ToggleGroupItem } from "@codefast/ui/toggle-group";
<ToggleGroup type="single" value={v} onValueChange={setV}>
<ToggleGroupItem value="a" aria-label="A">…</ToggleGroupItem>
</ToggleGroup>
API reference
Props for each part of the component. All native element props are also forwarded.
ToggleGroup
A set of related toggles sharing one value.
| Prop | Type | Default | Description |
|---|---|---|---|
| type | "single" | "multiple" | — | Single makes value a string; multiple makes it a string[]. |
| value / onValueChange | string | string[] / (value) => void | — | Controlled pressed item(s). In single mode value can be empty. |
| variant | "default" | "outline" | "default" | Visual style of the buttons. |
| size | "sm" | "default" | "lg" | "default" | Button size for the whole group. |
ToggleGroupItem
| Prop | Type | Default | Description |
|---|---|---|---|
| value | string | — | Identifier for this toggle (required). |
Accessibility
Built to be keyboard-navigable and screen-reader friendly out of the box.
| Key | Function |
|---|---|
| Tab | Moves focus into the group. |
| Arrow+Right | Moves to the next toggle. |
| Arrow+Left | Moves to the previous toggle. |
| Space | Toggles the focused button. |
- Single mode behaves as a radio group; multiple mode as a set of toggle buttons.
- Icon-only items must carry an aria-label, since there’s no visible text.
- In single mode, guard onValueChange against the empty string to keep a selection.
Guidelines
Conventions that keep usage consistent across an app.
Do
- Use single for mutually-exclusive choices (alignment).
- Use multiple for independent marks (bold, italic).
Don’t
- Don’t mix unrelated actions into one group.
- Don’t leave icon items without an accessible label.