Toggle Group
A wrapper that arranges a set of independent
Toggle Button children, gives
them a shared look and, from three toggles, one keyboard stop. It has no
selection state of its own: each toggle inside is a standalone on/off control
(a native button with aria-pressed) that owns its own pressed state, label
and form field. You insert the toggles via the default slot.
If you need exactly one active choice — a radio-style view switcher — use the Segmented Control instead.
Import
Section titled “Import”<script> import ToggleGroup from "@invisible-ui/svelte/ToggleGroup.svelte"; import ToggleButton from "@invisible-ui/svelte/ToggleButton.svelte";</script><script setup> import { ToggleGroup, ToggleButton } from "@invisible-ui/vue";</script>import { ToggleGroup, ToggleButton } from "@invisible-ui/react";<script type="module"> import "@invisible-ui/elements/define";</script>
<ds-toggle-group></ds-toggle-group><ds-toggle-button></ds-toggle-button>Styles
Section titled “Styles”separate(default) — each toggle keeps its own style, spaced by a gap.segmented— the toggles are joined into one control: their individual borders are dropped and the group draws a single outer border with thin dividers between items.
In Elements, place the <ds-toggle-button> children inside the group:
<ds-toggle-group label="Formatting" variant="segmented"> <ds-toggle-button label="Bold">B</ds-toggle-button> <ds-toggle-button label="Italic">I</ds-toggle-button></ds-toggle-group>| Prop | Type | Default | Description |
|---|---|---|---|
variant | "separate" | "segmented" | "separate" | Visual style. separate keeps each toggle's own style; segmented joins them. |
orientation | "horizontal" | "vertical" | "horizontal" | Layout axis (purely visual — the group has no keyboard navigation of its own). |
wrap | boolean | false | Let the toggles wrap onto multiple lines when they overflow the available width (e.g. a row of filter chips in a narrow panel). Only meaningful on a horizontal separate group; ignored when segmented. |
label | string | undefined | undefined | Optional container name for screen readers (the group's aria-label); names the container, not the items. |
| Prop | Type | Default | Description |
|---|---|---|---|
variant | ToggleGroupVariant | "separate" | Visual style. separate keeps each toggle's own style; segmented joins them. |
orientation | ToggleGroupOrientation | "horizontal" | Layout axis. Purely visual: the group has no keyboard navigation of its own. |
wrap | boolean | false | Let the toggles wrap onto multiple lines when they overflow the available width (e.g. a row of filter chips in a narrow panel). Meaningful on a horizontal separate group; ignored when segmented, which is one control. |
label | string | undefined | Optional container name for screen readers (the group's aria-label). It names the container, not the items; omit it when the toggles are unrelated. |
Slots: default.
| Prop | Type | Default | Description |
|---|---|---|---|
variant | ToggleGroupVariant | "separate" | Visual style. separate keeps each toggle's own style; segmented joins them. |
orientation | ToggleGroupOrientation | "horizontal" | Layout axis. Purely visual: the group has no keyboard navigation of its own. |
wrap | boolean | false | Let the toggles wrap onto multiple lines when they overflow the available width (e.g. a row of filter chips in a narrow panel). Meaningful on a horizontal separate group; ignored when segmented, which is one control. |
label | string | — | Optional container name for screen readers (the group's aria-label). It names the container, not the items; omit it when the toggles are unrelated. |
children | ReactNode | — | The ToggleButtons. |
| Attribute | Reactive | Description |
|---|---|---|
variant | yes | separate|segmented |
orientation | yes | horizontal|vertical |
wrap | yes | |
label | yes |
Reactive attributes re-render the element when they change after the first render.
Accessibility
Section titled “Accessibility”- The group is a
role="group", not a toolbar. Each toggle is an independent native button witharia-pressed; Enter and Space toggle it. - With three or more toggles the group is one Tab stop. The arrow keys move focus between the enabled toggles and wrap at the ends: Left and Right in a horizontal group, mirrored in right-to-left text, Up and Down in a vertical one. Home and End jump to the first and the last toggle. Tab returns to the toggle that had focus last.
- With one or two toggles each toggle is its own Tab stop and the arrow keys do nothing.
- Inside a Toolbar the toolbar’s keys apply to the toggles and the group adds none.
- Moving focus never changes a toggle. When toggles are added or removed, focus stays where it was; when the focused toggle is removed, its neighbour takes focus.
- The optional
labelbecomes the group’saria-label— a container name (e.g. “Formatting”) that gives screen readers context (“group, Formatting”). It is optional and different in nature from a form label: it names the container, it does not label the items (each toggle carries its own name). If the toggles are unrelated, omit it entirely. - Assistive technology: not tested.
Example
Section titled “Example”<ToggleGroup label="Formatting"> <ToggleButton label="Bold" pressed={bold} onPressedChange={(p) => (bold = p)}>B</ToggleButton> <ToggleButton label="Italic" pressed={italic} onPressedChange={(p) => (italic = p)}>I</ToggleButton></ToggleGroup>In React, the toggles are the group’s children:
<ToggleGroup label="Formatting" variant="segmented"> <ToggleButton label="Bold">B</ToggleButton> <ToggleButton label="Italic">I</ToggleButton></ToggleGroup>Filter chips
Section titled “Filter chips”Multi-select filter chips are just a wrap group of check toggles: each is a
toggle button, the checkmark makes the selection explicit, and wrap lets the
row flow onto multiple lines in a narrow container.
<ToggleGroup label="Filter by topic" wrap> {#each topics as topic (topic.id)} <ToggleButton check pressed={active.has(topic.id)} onPressedChange={(on) => toggle(topic.id, on)} > {topic.label} </ToggleButton> {/each}</ToggleGroup>Themeable via --ds-toggle-* and --ds-toggle-group-*.