Segmented control | Arcadia Design

ThemeSystem follows your device

import { useState } from "react";
import { SegmentedControl } from "@arcadia/ui";

function ThemeSetting() {
  const [theme, setTheme] = useState("system");
  return (
    <div {...sx("cmp-setting", cmp.setting)}>
      <span {...sx("cmp-setting-text", cmp.settingText)}>
        <span {...sx("cmp-setting-label", cmp.settingLabel)}>Theme</span>
        <span {...sx("cmp-setting-hint", cmp.settingHint)}>System follows your device</span>
      </span>
      <SegmentedControl
        aria-label="Theme"
        items={THEMES}
        value={theme}
        onValueChange={setTheme}
      />
    </div>
  );
}

TSX

import { SegmentedControl } from "@arcadia/ui";

<SegmentedControl
  aria-label="View"
  defaultValue="list"
  items={[
    { value: "list", label: "List" },
    { value: "grid", label: "Grid" },
  ]}
/>

One option is always chosen, and pressing the current one does nothing. At md the choice is a solid pill, white with night-ink text at night and night ink with white text by day, inside a track ringed at 10%; sm keeps a quiet thumb for toolbars. The thumb is measured from the pressed item and moves on the morph spring (--ease-morph); on first paint it appears in place. Use it for two to five options; beyond that, use a Menu. An item's icon sits beside its label, framed and stroked by the label's text; an icon-only item draws it standalone (16, 14 at sm). The thumb marks the selection, never the glyph.

The solid pill is an ink layer holding a copy of the labels in the inverse colour, clipped to the pressed item, so the pill and its inverted text move as one, mid-slide included, and look the same on any surface. A blend mode would invert whatever sits behind the control, and drop the pill inside a fading dialog or a blurred page swap.

Segmented Control or Tabs? A Segmented Control picks a value: a setting, a filter, a view. When each option has its own panel of content, use Tabs with the segmented look, which adds the tab roles.

Examples

Icon only

An icon-only item's label becomes its aria-label and its title.

import { SegmentedControl } from "@arcadia/ui";

<SegmentedControl
  size="sm"
  aria-label="Theme"
  defaultValue="system"
  items={THEMES.map((t) => ({ ...t, iconOnly: true }))}
/>

A hint per choice

When a choice's label cannot say what it does, its item takes a hint: a tooltip on that segment, and its aria-description.

import { SegmentedControl } from "@arcadia/ui";

<SegmentedControl aria-label="When you send" defaultValue="queue"
  items={[
    { value: "queue", label: "Queue", hint: "Sent when the agent finishes." },
    { value: "steer", label: "Steer", hint: "Read at the agent's next step, without stopping it." },
  ]} />

The sentence waits there instead of sitting under the control.

Stretch

stretch shares the full width equally, for a control that heads a panel.

import { SegmentedControl } from "@arcadia/ui";

<SegmentedControl stretch aria-label="Mode" items={MODES} defaultValue="plan" />

Kind and sizeShow interaction states

SmallMediumText

Icon and text

Icon only

Disabled item

Disabled

rootStyle takes where the control sits (margins, self-alignment, flex and grid placement, size bounds) and the knobs below, each a token of its kind. A colour, a raw length or any other property is a type error: a look that comes up twice becomes a variant.

TSX

import * as stylex from "@stylexjs/stylex";

const styles = stylex.create({
  // a looser track
  roomy: { "--segmented-pad": "var(--space-1)" },
});

<SegmentedControl items={items} rootStyle={styles.roomy} />

--segmented-item-h: Ref<Control>Default var(--control-sm); Item height.
--segmented-item-px: Ref<Space>Default var(--space-2-5); Item inline padding (a labelled item adds --space-0-5).
--segmented-pad: Ref<Space>Default var(--space-0-75); Track padding around the items.
--segmented-solid: PaintDefault var(--bg-inverse); The solid choice's fill (SegmentedControl at md).
--segmented-solid-fg: PaintDefault var(--text-inverse); The solid choice's label colour (SegmentedControl at md).

--segmented-solid and --segmented-solid-fg paint the solid choice at md. Tabs with the segmented look take the same knobs on their TabsList.

A toggle group: one tab stop, with arrow keys moving between the options. Give the control an aria-label (or aria-labelledby on a visible label, as in a settings row) so it is announced as "Theme" rather than a bare group.

←→: Move focus between options
EnterSpace: Choose the focused option