Grouped toggle buttons with a clearable string[] selection model. Prefer Content Switcher for exclusive view modes as segments.
Also known as: button group, option group, toggle buttons, multi select toggles
Install with the CLI, or copy the component source into your project.
Add toggle-group (npm)
1npx --yes -p @default-file/ui df-ui add toggle-group
Single-select group.
Default and outline styles.
Small, default, and large.
Lay items out horizontally or vertically.
Adjust corner rounding from a full pill to a tighter square.
Press more than one item at a time.
Grouped toggle buttons with a shared string[] value. Single-select is clearable: pressing the selected item clears the selection. Multi-select adds and removes values. Prefer Content Switcher for exclusive view modes as radio segments, and Switch for a single binary setting.
| Prop | Type | Default | Notes |
|---|---|---|---|
| variant | "default" | "outline" | "default" | Visual style for items. |
| size | "default" | "sm" | "lg" | "default" | Item height and type size. |
| radius | "xxs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4xl" | "full" | - | Corner radius of the group. Defaults to a pill look. |
| cornerShape | "round" | "smooth" | - | Instance corner curve. Omit to inherit --df-corner-shape from the theme (set at create/init). |
| spacing | number | 2 | Gap between items (design-scale units). |
| orientation | "horizontal" | "vertical" | "horizontal" | Layout direction. Also sets the roving tabindex arrow-key axis. |
| multiple | boolean | false | When false, at most one value is selected and pressing the selected item clears to []. When true, values accumulate and each press toggles membership. |
| value | string[] | - | Controlled selected values. Always an array, including single-select. |
| defaultValue | string[] | [] | Uncontrolled initial values. |
| onValueChange | (value: string[]) => void | - | Called when selection changes. |
| disabled | boolean | false | Disable the whole group. |
| Prop | Type | Default | Notes |
|---|---|---|---|
| value | string | - | Item value (required). |
| variant | "default" | "outline" | - | Override group variant for this item. |
| size | "default" | "sm" | "lg" | - | Override group size for this item. |
| disabled | boolean | - | Non-interactive item. |
| children | ReactNode | - | Item label or icon. |
Selection (toggle button): Each item is a button with aria-pressed reflecting selection. Single and multi modes use the same pressed model, not radio or checkbox roles. Roving tabindex (Arrow keys): Arrow keys move focus along orientation. Home and End jump to the first and last enabled item. Space and Enter activate the focused item.
Theme defaults live on :root. Override these globally or on a local host.
| Token | Type | Default | Notes |
|---|---|---|---|
| --df-toggle-radius | CSS length | var(--radius-4xl) | Instance variable set from the radius prop. Falls back to --radius-4xl. |
| --gap | CSS length | calc(2 * var(--spacing-unit)) | Instance variable set from the spacing prop. |
| --muted | CSS color | var(--df-neutral-50) | Outline variant hover fill. |
| --background | CSS color | var(--df-neutral-0) | Selected item fill. |
| --border | CSS color | var(--df-neutral-100) | Outline variant border. |
| --foreground | CSS color | var(--df-neutral-900) | Selected item label. |
| --df-corner-shape | CSS corner-shape | var(--df-corner-shape-round) | Theme corner curve for all kit chrome. round = circular arcs; smooth = continuous squircle. Set with df-ui init --corner-shape, or override on :root. Default round. |