Skip to content

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.

<script>
import ToggleGroup from "@invisible-ui/svelte/ToggleGroup.svelte";
import ToggleButton from "@invisible-ui/svelte/ToggleButton.svelte";
</script>
  • 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>
PropTypeDefaultDescription
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).
wrapbooleanfalseLet 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.
labelstring | undefinedundefinedOptional container name for screen readers (the group's aria-label); names the container, not the items.
  • The group is a role="group", not a toolbar. Each toggle is an independent native button with aria-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 label becomes the group’s aria-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.
<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>

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-*.