Contents

Components

Toggle group

Segmented controls for picking one option or several, plus the standalone Toggle they are made of.

Props
type
variant
size
import * as ToggleGroup from "@sideby/ui/toggle-group";

<ToggleGroup.Root type="single" value="chat" aria-label="Show">
  <ToggleGroup.Item value="chat">Chat</ToggleGroup.Item>
  <ToggleGroup.Item value="people">People</ToggleGroup.Item>
  <ToggleGroup.Item value="captions">Captions</ToggleGroup.Item>
</ToggleGroup.Root>

When to use it

A toggle group is a small set of options that stay visible side by side. With type="single" it is a segmented control: exactly one option, like a radio group that fits in a toolbar. With type="multiple" each option switches on and off on its own. Past four or five options, or when the labels get long, reach for a select instead.

The selected segment takes the accent: accent text on the accent tint inside an accent-edged pill. The pill appearing around the chosen option is the cue that does not depend on colour.

One of a few

Single, labelled
Sort
import * as ToggleGroup from "@sideby/ui/toggle-group";

<span id="sort-label">Sort</span>
<ToggleGroup.Root type="single" value="newest" aria-labelledby="sort-label">
  <ToggleGroup.Item value="newest">Newest</ToggleGroup.Item>
  <ToggleGroup.Item value="oldest">Oldest</ToggleGroup.Item>
</ToggleGroup.Root>

Pick several

Multiple
Show
import * as ToggleGroup from "@sideby/ui/toggle-group";

<span id="panels-label">Show</span>
<ToggleGroup.Root type="multiple" value={["chat"]} aria-labelledby="panels-label">
  <ToggleGroup.Item value="chat">Chat</ToggleGroup.Item>
  <ToggleGroup.Item value="people">People</ToggleGroup.Item>
  <ToggleGroup.Item value="captions">Captions</ToggleGroup.Item>
</ToggleGroup.Root>

A single toggle

Toggle is one pressable button that stays pressed. It is the part every group item is built from, and it works on its own for a single on-off action in a toolbar. An icon-only toggle needs an aria-label. Keep that label fixed (“Mute”) and let the pressed state say whether it is on.

Toggle
import { Toggle } from "@sideby/ui/toggle";
import VolumeOff from "@lucide/svelte/icons/volume-off";

<Toggle variant="outline" aria-label="Mute"><VolumeOff aria-hidden="true" /></Toggle>
<Toggle variant="outline">Captions</Toggle>

Keyboard

  • Tab moves into the group, landing on the selected item, and Tab again leaves it. The whole group is one stop.
  • Arrow keys move between items. Home and End jump to the first and last.
  • Space or Enter selects the focused item, or flips it in a multiple group.
  • A single group uses radio semantics (role="radio" with aria-checked). A multiple group and a standalone toggle use aria-pressed.

Pressing the selected item of a single group clears it, which is Bits UI’s behaviour. When one option must always be chosen, ignore the empty value in onValueChange and keep the last one.

Copy

Item labels are one word where possible, in the label voice: Newest, Oldest, Chat. Name the group with a visible label, tied by aria-labelledby, that says what is being chosen: Sort, Show.