Segmented Control

Anatomy

import {SegmentedControl} from '@staffbase/design';

<SegmentedControl.Root>
  <SegmentedControl.Item />
</SegmentedControl.Root>;

Examples

With icons

Variants

API reference

Root

Item

When to use

• To switch between two to five mutually exclusive views of the same object, such as Editor, Preview, and Summary.
• To filter one list by a single closely related option at a time, such as All, Unread, and Archived.
• When all options are equally important and benefit from being visible at once without opening a menu.
• When the labels are short — one or two words each — so the whole control fits on one line.
• When selecting an option takes effect immediately, without a separate confirm step.

When not to use

• Don’t use a segmented control to navigate between distinct panels of page content — use Tabs instead.
• Don’t use a segmented control when more than one option can be active at the same time — use Checkbox instead.
• Don’t use a segmented control to filter a list by many values or by values that are unknown up front — use Filter instead.
• Don’t use a segmented control for more than five options or for labels longer than two words — use Select instead.
• Don’t use a segmented control for a single on-or-off setting — use Switch instead.
• Don’t use a segmented control for a form input that needs a visible label, helper text, or validation — use Radio inside a Field instead.
• Don’t use a segmented control to trigger an action such as saving, publishing, or deleting — use Button instead.

How to use

Structure

• Group only closely related choices that affect the same object, state, or view.
• Keep the control between two and five items; a single item has nothing to switch between.
• Set defaultValue on SegmentedControl.Root so exactly one item is always selected — a segmented control has no empty state.
• Give every SegmentedControl.Item a unique value.
• Apply the selection immediately when an item is chosen; don’t require a separate confirm action.
• Keep the item set stable — don’t add or remove items in response to the current selection.

Variants

• Use variant="studio" (the default) when the control sits in the Studio header.
• Use variant="content" when the control sits in the content area, where the selected item needs a lighter fill.
• Use one variant per screen region; don’t mix studio and content in the same toolbar.

Icon & label

• Add a leading or trailing icon only when the icon is universally recognized for that option, such as a pencil for Editor.
• Always pair an icon with a visible text label; don’t use icon-only items.
• Use the same icon slot for every item in a group — all leading or all trailing.
• Give every item an icon or give none of them an icon; don’t mix icon and text-only items in one group.
• Don’t add decorative icons that repeat what the label already says.

Badge

• Place a Badge only in the trailing slot of an item, after the label.
• Use a badge only for a count that belongs to that option, such as unresolved comments.
• Give every badge an a11yDescription that explains the count, such as “12 unresolved comments”.
• Set truncate so counts above nine render as 9+ and the item keeps its width.
• Don’t put a badge on more than one item at a time — it competes with the selected state.

Layout & spacing

• The control sizes to its content and stays inline; it doesn’t stretch to fill its container.
• Keep label lengths close to each other so segments look evenly balanced.
• Don’t crowd the control — beyond five segments labels compress and become hard to scan.
• Place the control next to the content it changes, so the relationship is obvious.

Accessibility

• Always set aria-label on SegmentedControl.Root — it names the radio group for assistive technology.
• Name the control after what it changes, such as “Editing mode”, not after the selected value.
• Tab moves focus into and out of the control; arrow keys move between items and select as they move, wrapping at both ends.
• Never rely on the selected item’s fill alone to communicate state — keep each label readable in every state.
• Don’t nest interactive elements such as buttons or links inside an item; the whole item is the control.

Content & UX copy

• Keep labels to one or two words in Title Case.
• Keep the label style consistent across a group — all nouns or all verbs, never mixed.
• Use the same level of specificity for every label, such as Editor, Preview, and Summary.
• Don’t end labels with punctuation and don’t use sentences.