Segmented Control

Pick one of a few options from a row of buttons, with an indicator that slides to the choice.

Use a segmented control to switch between a few views or settings, like List and Grid. It works like a radio group, with one value and a single tab stop, and its indicator slides to the checked item.

"use client"

import { Field, FieldLabel } from "@ui-sdk/react/field"
import {
  SegmentedControl,
  SegmentedControlIndicator,
  SegmentedControlItem,
} from "@ui-sdk/react/segmented-control"

function Example() {
  return (
    <Field>
      <FieldLabel>View</FieldLabel>
      <SegmentedControl defaultValue="list">
        <SegmentedControlIndicator />
        <SegmentedControlItem value="list">List</SegmentedControlItem>
        <SegmentedControlItem value="grid">Grid</SegmentedControlItem>
        <SegmentedControlItem value="board">Board</SegmentedControlItem>
      </SegmentedControl>
    </Field>
  )
}

export { Example }

Choose Grid, then use the arrow keys to move between views. The label above names the control, as in any field.

Installation

npm install @ui-sdk/react @ui-sdk/core

Composition

Use the following composition to build a SegmentedControl:

SegmentedControl
├── SegmentedControlIndicator
├── SegmentedControlItem
└── SegmentedControlItem

Give each item a value. The control's value is the checked item's value, and the indicator sits behind that item.

Usage

Import the parts and put them together:

import {
  SegmentedControl,
  SegmentedControlIndicator,
  SegmentedControlItem,
} from "@ui-sdk/react/segmented-control"

function Example() {
  return (
    <SegmentedControl aria-label="View" defaultValue="list">
      <SegmentedControlIndicator />
      <SegmentedControlItem value="list">List</SegmentedControlItem>
      <SegmentedControlItem value="grid">Grid</SegmentedControlItem>
    </SegmentedControl>
  )
}

export { Example }

Name the control with aria-label, or put it in a Field whose label names it. Without defaultValue, nothing starts checked and Tab enters on the first enabled item.

SegmentedControlIndicator measures the checked item. Position it inside the control and use its CSS variables to draw the background that slides to the choice. It measures again when an item or the control changes size, and has no box while nothing is checked.

[data-slot="segmented-control"] {
  position: relative;
  display: inline-flex;
  isolation: isolate;
}

[data-slot="segmented-control-indicator"] {
  position: absolute;
  z-index: -1;
  top: var(--segmented-control-indicator-top);
  left: var(--segmented-control-indicator-left);
  width: var(--segmented-control-indicator-width);
  height: var(--segmented-control-indicator-height);
  transition-property: top, left, width, height;
  transition-duration: 200ms;
}

Vertical

Set orientation="vertical" to stack the items. Arrow keys on both axes still move between them, as in any radio group, and data-orientation on every part lets one stylesheet lay out both directions.

"use client"

import { Field, FieldLabel } from "@ui-sdk/react/field"
import {
  SegmentedControl,
  SegmentedControlIndicator,
  SegmentedControlItem,
} from "@ui-sdk/react/segmented-control"

function Example() {
  return (
    <Field>
      <FieldLabel>Vertical alignment</FieldLabel>
      <SegmentedControl orientation="vertical" defaultValue="middle">
        <SegmentedControlIndicator />
        <SegmentedControlItem value="top">Top</SegmentedControlItem>
        <SegmentedControlItem value="middle">Middle</SegmentedControlItem>
        <SegmentedControlItem value="bottom">Bottom</SegmentedControlItem>
      </SegmentedControl>
    </Field>
  )
}

export { Example }

Choose Bottom, then press the Up arrow. The indicator follows down the column.

Disabled

Set disabled on the control or on one item. Disabled items can't be focused or checked, and arrow keys skip them. A disabled control submits nothing.

"use client"

import {
  SegmentedControl,
  SegmentedControlIndicator,
  SegmentedControlItem,
} from "@ui-sdk/react/segmented-control"

function Example() {
  return (
    <div data-slot="stack">
      <SegmentedControl aria-label="Theme" defaultValue="system" disabled>
        <SegmentedControlIndicator />
        <SegmentedControlItem value="light">Light</SegmentedControlItem>
        <SegmentedControlItem value="dark">Dark</SegmentedControlItem>
        <SegmentedControlItem value="system">System</SegmentedControlItem>
      </SegmentedControl>
      <SegmentedControl aria-label="Billing period" defaultValue="monthly">
        <SegmentedControlIndicator />
        <SegmentedControlItem value="monthly">Monthly</SegmentedControlItem>
        <SegmentedControlItem value="yearly">Yearly</SegmentedControlItem>
        <SegmentedControlItem value="lifetime" disabled>
          Lifetime
        </SegmentedControlItem>
      </SegmentedControl>
    </div>
  )
}

export { Example }

The Theme control is disabled. In Billing period, Lifetime is disabled, so the arrow keys move between Monthly and Yearly.

Controlled

Pass value and update it in onValueChange. Call details.cancel() in the callback to keep the current value. A controller from createSegmentedControlController() checks an item from anywhere, like the Show Month button below. Create one controller per mounted control.

Console

"use client"

import {
  createSegmentedControlController,
  SegmentedControl,
  SegmentedControlIndicator,
  SegmentedControlItem,
} from "@ui-sdk/react/segmented-control"
import * as React from "react"
import { useLog } from "./log"

function Example() {
  const log = useLog()
  const [range] = React.useState(() => createSegmentedControlController())
  const [value, setValue] = React.useState<string | null>("week")

  return (
    <div>
      <div data-slot="controls">
        <button type="button" onClick={() => range.setValue("month")}>
          Show Month
        </button>
      </div>
      <SegmentedControl
        aria-label="Range"
        value={value}
        onValueChange={(next, details) => {
          setValue(next)
          log(`value: ${next} (${details.reason})`)
        }}
        controller={range}
      >
        <SegmentedControlIndicator />
        <SegmentedControlItem value="day">Day</SegmentedControlItem>
        <SegmentedControlItem value="week">Week</SegmentedControlItem>
        <SegmentedControlItem value="month">Month</SegmentedControlItem>
      </SegmentedControl>
    </div>
  )
}

export { Example }

Choose Day, then press Show Month. The console logs each change and its reason.

See State and Events for controlled state, cancellation and debugging.

Form

Each item renders a hidden native radio, so the control takes part in forms. Set name to submit the checked value; nothing submits without a name or a checked item. required blocks submission until there's a choice, form joins a form by its id from elsewhere on the page, and a reset returns to defaultValue.

"use client"

import { Field, FieldDescription, FieldLabel } from "@ui-sdk/react/field"
import {
  SegmentedControl,
  SegmentedControlIndicator,
  SegmentedControlItem,
} from "@ui-sdk/react/segmented-control"
import { useLog } from "./log"

function Example() {
  const log = useLog()

  return (
    <form
      data-slot="stack"
      onSubmit={(event) => {
        event.preventDefault()
        const data = new FormData(event.currentTarget)
        log(`Saved theme=${data.get("theme")}, density=${data.get("density")}`)
      }}
    >
      <Field>
        <FieldLabel>Theme</FieldLabel>
        <SegmentedControl name="theme" required defaultValue="system">
          <SegmentedControlIndicator />
          <SegmentedControlItem value="light">Light</SegmentedControlItem>
          <SegmentedControlItem value="dark">Dark</SegmentedControlItem>
          <SegmentedControlItem value="system">System</SegmentedControlItem>
        </SegmentedControl>
        <FieldDescription>
          System follows your device's setting.
        </FieldDescription>
      </Field>
      <Field>
        <FieldLabel>Density</FieldLabel>
        <SegmentedControl name="density" defaultValue="comfortable">
          <SegmentedControlIndicator />
          <SegmentedControlItem value="compact">Compact</SegmentedControlItem>
          <SegmentedControlItem value="comfortable">
            Comfortable
          </SegmentedControlItem>
        </SegmentedControl>
      </Field>
      <div data-slot="row">
        <button type="submit" data-variant="solid">
          Save
        </button>
        <button type="reset">Reset</button>
      </div>
    </form>
  )
}

export { Example }

Choose Dark and Compact, then press Save. The console logs both values, and Reset returns each control to its default.

Read-Only

Set readOnly to keep the value while still letting people focus the items. Arrow keys move focus without checking anything, and the value still submits with a form.

Loop

Arrow keys wrap from the last item to the first. Set loop to false to stop at the ends.

<SegmentedControl aria-label="View" defaultValue="list" loop={false}>
  ...
</SegmentedControl>

Styling

Parts are unstyled. Use data-checked and data-unchecked for the checked item, and data-disabled, data-readonly and data-required for the rest. data-orientation is on the control and the indicator.

Each part has a data-slot, such as segmented-control-item, and its state attributes are listed under Data Attributes.

SegmentedControlIndicator

Variable	What it holds
`--segmented-control-indicator-left`	Distance from the control's left edge to the checked item.
`--segmented-control-indicator-right`	Distance from the control's right edge to the checked item.
`--segmented-control-indicator-top`	Distance from the control's top edge to the checked item.
`--segmented-control-indicator-bottom`	Distance from the control's bottom edge to the checked item.
`--segmented-control-indicator-width`	Width of the checked item.
`--segmented-control-indicator-height`	Height of the checked item.

Data Attributes

SegmentedControl

[data-slot="segmented-control"]

Attribute	What it means
`data-orientation`	`horizontalvertical`Which way the items run.
`data-readonly`	Present when the control is read-only.
`data-required`	Present when the control is required.
`data-disabled`	Present when disabled, by its own prop, the control or a `<fieldset>`.

SegmentedControlItem

[data-slot="segmented-control-item"]

Attribute	What it means
`data-checked`	Present on the checked item.
`data-readonly`	Present when the control is read-only.
`data-required`	Present when the control is required.
`data-unchecked`	Present on items that aren't checked.
`data-disabled`	Present when disabled, by its own prop, the control or a `<fieldset>`.

SegmentedControlIndicator

[data-slot="segmented-control-indicator"]

Attribute	What it means
`data-orientation`	`horizontalvertical`Which way the items run.

API Reference

Props and callbacks are the same as below, as React props.

SegmentedControl

value?T | null: The checked item's value. Pass it to control the segmented control. null checks nothing.
defaultValue?T | null: The item checked at first, when uncontrolled. A form reset returns to it.
onValueChange?((value: T | null, details: ChangeDetails<SegmentedControlValueChangeReason>) => void): Runs when a user or a form reset wants to change the value. details.reason says why, and details.cancel() stops it.
disabled?boolean: Disables every item: they can't be focused or changed, and the value isn't submitted.
readOnly?boolean: Keeps the items focusable and the value submitted, but stops changes.
required?boolean: Blocks form submission until an item is checked, with the browser's own message.
name?string: The name the value submits under. Without one, the segmented control submits nothing.
form?string: The id of a form to belong to, when the segmented control isn't inside that form.
loop?boolean: Whether arrow keys wrap from the last item to the first.
orientation?SegmentedControlOrientation: Which way the items run, for styling and for screen readers. Arrow keys on both axes move between items either way, as in any radio group.
controller?{ getValue: () => T | null; setValue: (value: T | null, details?: SegmentedControlChangeOptions) => boolean; focus: () => void; }: Checks items from anywhere. Create one with createSegmentedControlController().
debug?boolean: Logs every state change with its reason to the console, in development builds.

SegmentedControlItem

valuestring: What the value becomes when this item is checked.
disabled?boolean: Skips the item, like a disabled native radio: arrow keys pass it and it can't be focused or checked.

State

What render functions, state-based class names and slots receive.

valuestring | null: The checked item's value.
disabledboolean: Whether the segmented control is disabled, by itself or by a <fieldset>.
readOnlyboolean: Whether it's read-only: arrow keys still move focus, but nothing changes the checked item.
requiredboolean: Whether a form won't submit until an item is checked.
orientationSegmentedControlOrientation: Which way the items run.

checkedboolean: Whether this item is the control's value, which the indicator sits behind.
disabledboolean: Whether this item is disabled, by itself, the segmented control or a <fieldset>.
readOnlyboolean: Whether the control is read-only, so pressing this item changes nothing.
requiredboolean: Whether a form won't submit until an item is checked.

valuestring | null: The checked item's value, which the indicator sits behind.
orientationSegmentedControlOrientation: Which way the items run.

Reasons

details.reason says why the checked value changed.

item-pressMouseEvent | KeyboardEvent: A member of a collection was chosen: a menu item, a tab, a radio or a checkbox item.
list-navigationKeyboardEvent: Arrow, Home or End keys moved the selection, typing picked an item, or Ctrl or ⌘ with A selected every item of a listbox.
resetnone: A form reset.
restorenone: The browser restored state, like after going back, or a saved value was read back from storage.
imperativenone: A controller or api call, or a property set on a web component.

Controller

Create one with createSegmentedControlController() and pass it as controller.

Every write method takes an optional { reason, event }, runs the change callback like a press, and returns false when the change is canceled.

getValue()() => T | null: The checked item's value.
setValue(value, details?)(value: T | null, details?: SegmentedControlChangeOptions | undefined) => boolean: Checks an item, as a user would. Disabled items and read-only controls ignore it.
focus()() => void: Moves focus to the checked item, or the first one.

Events

Callbacks get the new value first, then the details.

Prop	On	Receives
`onValueChange`	`SegmentedControl`	`(value, details)`: the checked value, and the reason

Accessibility

A segmented control is a radio group, so it follows the WAI-ARIA radio group pattern and behaves like native radios that share a name. Each SegmentedControlItem renders a button with the radio role, and a hidden native radio that takes part in forms. The indicator is presentational, so screen readers skip it.

Keyboard

Key	Does
Tab	Moves into the control, onto the checked item or the first enabled one
Arrow keys	Move to the next or previous item and check it, skipping disabled ones
Space	Checks the focused item
Enter	Submits its form

Tested Behavior

Every line below is an automated test.

Selection

The default item is checked, and only that one.
Clicking an item checks it and says why.
Clicking a disabled item does nothing.
A change can be cancelled.
A controller checks an item.

Keyboard

Tab lands on the checked item, and the next Tab leaves.
Arrow keys on both axes check the next item, skip disabled ones and wrap.

Orientation

A segmented control is horizontal unless it says otherwise.
A vertical segmented control reports it.

Indicator

The indicator covers the checked item.
The indicator follows the checked item.
The indicator covers the checked item in a vertical control.
The indicator matches items with fractional widths exactly.
A scaled ancestor doesn't move the indicator off fractional items.
With nothing checked, the indicator has no box.

Forms

The checked value submits under the control's name.
A form reset checks the default item again.
A disabled control submits nothing, and its items can't be focused or checked.

Runs in React, Vue and web components.