Components

Toggle Group

Provides a shared state to a series of toggle buttons.

Stable

Anatomy

import {Toggle, ToggleGroup} from '@staffbase/spark';

<ToggleGroup>
  <Toggle />
</ToggleGroup>;

By default only one item in the group can be pressed at a time. Set multiple to let the user press several.

Use Toggle for each item inside the group. Give each one a unique value.

For a set of two to five closely related formatting or view options that belong to the same object, such as text alignment.
When the options sit together in a toolbar and the user switches between them frequently.
When each option takes effect immediately, without a separate save or confirm step.
When several options can be active at the same time and they share one topic, such as bold, italic, and underline.

Don’t use a Toggle Group for a single on-or-off option — use a standalone Toggle instead.
Don’t use a Toggle Group to switch between panels of page content — use Tabs instead.
Don’t use a Toggle Group for a labelled setting in a form or settings screen — use a Switch or Checkbox instead.
Don’t use a Toggle Group to choose between named views where labels need to stay readable — use a Segmented Control instead.
Don’t use a Toggle Group to trigger actions such as downloading or deleting — use a Button instead.

Group only options that act on the same object and belong to the same topic.
Every item must represent an on-or-off state, not a one-off action — Download and Delete are actions and belong in a Button, not in a Toggle Group.
Keep the group between two and five items; a single item has nothing to switch between.
Give every Toggle in the group a unique value.
Keep the item set stable — don’t add or remove items in response to the current selection.
Use a single icon as the content of every item in the group.

Three alignment options that act on the same object.

Don't

Download and Delete are actions, not states — they shouldn't be toggles at all.

By default only one item can be pressed at a time; pressing another item unpresses the previous one.
Use multiple when the options combine, such as bold, italic, and underline.
Use defaultValue for an uncontrolled group, or value with onValueChange when the state lives in your app.
value and defaultValue are always arrays, in single and multiple selection alike.
Unlike a Segmented Control, a Toggle Group can have nothing pressed — don’t rely on one item always being active.

Multiple selection lets several related options be pressed at once.

The group is a flex row that sizes to its content; it doesn’t stretch to fill its container.
Add spacing between items with a gap utility class rather than margins on each Toggle.
Set orientation="vertical" only when the toolbar itself is vertical; arrow keys follow the orientation.
Place the group next to the content it changes, so the relationship is obvious.

aria-label is required on ToggleGroup — it names the group for assistive technology.
Name the group after what it changes, such as “Text alignment”, not after the pressed item.
Always set aria-label on each Toggle inside the group; the group name doesn’t name the individual items.
Tab moves focus into and out of the group; arrow keys move between items and loop at both ends.
Never rely on the pressed fill alone — keep each icon legible in every state.

Announced to screen readers

“Text alignment group, Left Align, toggle button, pressed”

The group name and the item state are announced together.

Keep each item’s aria-label to one or two words in Title Case, such as “Left Align”.
Keep the label style consistent across the group — all of the same kind, never mixed.
Use the same wording for both states of an item; don’t switch the label when it becomes pressed.
Don’t end labels with punctuation and don’t write them as sentences.