---
title: "SegmentedControl"
description: "A row of mutually exclusive options with exactly one chosen at a time, for switching a single view between a small set of windows."
url: "https://opsinjs.pensievelabs.org/docs/components/segmented-control"
source: "https://opsinjs.pensievelabs.org/docs/components/segmented-control.md"
section: "Components"
status: "shipped"
kind: "component"
category: "navigation"
reviewed: "2026-09-20"
reviewer: "engineering"
aliases: ["segmented buttons", "toggle group"]
implemented: true
---

> Elements written as `<PascalCase … />` below are opsinjs documentation
> components. Their attributes are the content: the values they render are
> generated from `tokens/*.json` and `registry/catalogue.ts` and are
> published separately at https://opsinjs.pensievelabs.org/r/index.json and under the Reference
> section.
> `<StubNotice>` IS THE EXCEPTION, AND IT IS THE ONE TO READ. It is a
> paired element rather than a self-closing one, and the text between
> its opening and closing tags is prose an author wrote, reproduced
> below word for word. That prose is where this page says whether the
> component has been reviewed. Read the children, not only the
> attributes.

<StubNotice
  name="segmented-control"
  status="shipped"
  questions="[
  &#x22;No contrast pair has been measured for the selected segment against the track or for its hairline, so greyscale legibility is argued rather than measured.&#x22;,
  &#x22;Nobody has listened to this control in a screen reader, so whether \&#x22;radiogroup\&#x22; is the register a reader expects for a button-like row is unchecked.&#x22;,
  &#x22;Forced colours and `prefers-contrast: more` are unhandled, so whether the selected segment still reads as selected in those modes is untested.&#x22;,
]"
>
  Audited against WCAG 2.2 AA. Clinical review pending.
</StubNotice>

## Usage [#usage]

<ComponentInstall name="segmented-control" unbuilt="false" importPath="@/components/ui/segmented-control" dependencies="[&#x22;@base-ui/react&#x22;]" />

```tsx
import { SegmentedControl } from "@/components/ui/segmented-control"
```

```tsx
<SegmentedControl
  label="Chart window"
  value={chartWindow}
  onValueChange={setChartWindow}
  options={[
    { value: "day", label: "Day" },
    { value: "week", label: "Week" },
    { value: "month", label: "Month" },
  ]}
/>
```

## Examples [#examples]

<ComponentPreview name="segmented-control" />

### Switching a chart window [#switching-a-chart-window]

The three options set the window of one chart rather than swapping between three
charts, which is why it is a radiogroup. The chart is a placeholder.

<ComponentPreview name="segmented-control-switching-a-chart-window" kind="example" align="start" />

## When to use it [#when-to-use-it]

<WhenToUse
  use="[
  &#x22;Switching one view between a small set of mutually exclusive windows, such as a chart's day, week or month range.&#x22;,
  &#x22;Choosing one setting from two to five short, comparable options that fit on one row and read as siblings.&#x22;,
  &#x22;A choice the reader changes often and wants the whole set in front of them.&#x22;,
]"
  avoid="[
  { case: &#x22;The options open different views with their own content, so choosing one swaps what the reader is looking at.&#x22;, instead: &#x22;tabs&#x22; },
  { case: &#x22;There are more than about five options, or the labels are long, so the row will not fit one line.&#x22;, instead: &#x22;field&#x22; },
  { case: &#x22;The control performs an action rather than setting a value, such as saving a reading.&#x22;, instead: &#x22;button&#x22; },
]"
/>

## Accessibility [#accessibility]

It is a radio group, so the row is one tab stop with a roving focus, with
`radiogroup` plus `radio` and `aria-checked` per segment for name, role and
value. Selection is carried three ways and never by colour alone: `aria-checked`,
the card surface lifting the segment off the track, and a hairline. That lift is one
`aria-hidden` puck which glides to the next choice on `spring-snap`, and until the
script has measured the row the chosen segment draws the same lift itself. Under
`prefers-reduced-motion` the puck moves in one frame. The audit
moved the 44px hit-area floor from the height axis alone onto both axes, matching
`scale-input` and `tab-bar`, because a single-character label or the `sm` size
could shrink a segment below the house minimum.

**Residual items.**

* `label` is applied only as the group's `aria-label`, so there is no persistent visible group heading. Every option carries visible text, so the choices are seen, but a visible group label is a recommended enhancement, deferred as one repair across the wrappers that share this pattern.
* No contrast pair has been measured, so greyscale legibility of the selected segment is argued, not confirmed.

<KeyboardTable
  name="segmented-control"
  rows="[
  {
    keys: &#x22;Tab&#x22;,
    action: &#x22;Moves focus into the control, onto the selected segment&#x22;,
    notes: &#x22;The group is one tab stop. A disabled segment never takes it.&#x22;,
  },
  {
    keys: &#x22;Shift + Tab&#x22;,
    action: &#x22;Moves focus back out of the control&#x22;,
    notes: &#x22;One stop in reverse too, so focus leaves the whole row.&#x22;,
  },
  {
    keys: &#x22;Arrow Right, Arrow Down&#x22;,
    action: &#x22;Moves to the next segment and selects it&#x22;,
    notes: &#x22;Selection follows focus. It wraps, skips disabled segments and mirrors under right-to-left.&#x22;,
  },
  {
    keys: &#x22;Arrow Left, Arrow Up&#x22;,
    action: &#x22;Moves to the previous segment and selects it&#x22;,
    notes: &#x22;Wraps from the first segment to the last and skips disabled segments.&#x22;,
  },
  {
    keys: &#x22;Space&#x22;,
    action: &#x22;Selects the focused segment&#x22;,
    notes: &#x22;A segment is a role=\&#x22;radio\&#x22;, so Space is its activator.&#x22;,
  },
  {
    keys: &#x22;Enter&#x22;,
    action: &#x22;Does nothing&#x22;,
    notes: &#x22;The primitive cancels Enter, so a form is never submitted by accident.&#x22;,
  },
  {
    keys: &#x22;Home, End&#x22;,
    action: &#x22;Not bound&#x22;,
    notes: &#x22;The RadioGroup primitive disables them, so the browser's default applies.&#x22;,
  },
]"
/>

<ContrastReport component="segmented-control" />

## Props interface [#props-interface]

<PropsTable name="SegmentedControlProps" />

`value` and `onValueChange` make this controlled, with no internal selection
state. A `value` matching no option renders the row with nothing chosen and
raises a development warning. `label` is required: a radiogroup with no
accessible name is a defect the type system cannot otherwise prevent.

### Data attributes [#data-attributes]

<DataAttributesTable
  name="segmented-control"
  rows="[
  {
    attribute: &#x22;data-slot&#x22;,
    condition: &#x22;On the root and every inner part&#x22;,
    value: &#x22;segmented-control, segmented-control-indicator, segmented-control-segment, segmented-control-label&#x22;,
  },
  {
    attribute: &#x22;data-checked / data-unchecked&#x22;,
    condition: &#x22;On each segment, one or the other&#x22;,
    value: &#x22;Present with no value; reflects the choice&#x22;,
  },
  {
    attribute: &#x22;data-glide&#x22;,
    condition: &#x22;On the root once the puck has been measured and placed&#x22;,
    value: &#x22;Present with no value; the chosen segment hands its lift to the puck&#x22;,
  },
]"
/>
