SegmentedControl

Single-select segmented control: a compact, pill-shaped row of mutually exclusive options with one visibly selected, as a radiogroup with roving-tabindex arrow-key navigation. The selection indicator slides between options.

Status: beta. Group: form. Markdown version: /design-system/components/segmented-control.md

When to use

SegmentedControl is the single-select counterpart to ButtonGroup: a compact row of mutually exclusive options with one visibly selected, for switching a small closed set of views or modes inline without opening a menu (list/grid, day/week/month). It is controlled; value + onValueChange own the selection. Keep it to 2-5 short segments; if the options do not fit on one line, use Select. Selecting must only change the bound value, never commit or route.

When not to use

Do not use it for actions or navigation that commits/routes; use ButtonGroup or links. Selecting must only change the bound value.
Do not overflow it; if the options do not fit on one line, use Select.

Look-alikes

ButtonGroup: Do not use it for actions or navigation that commits/routes; use ButtonGroup or links. Selecting must only change the bound value.
Select: Do not overflow it; if the options do not fit on one line, use Select.

Props

SegmentedControl props
Prop	Type	Default	Description	Required
`items`	`SegmentedControlItem[]`	none	Segments to render, in order.	Yes
`value`	`string`	none	Currently selected value (controlled).	Yes
`onValueChange`	`(value: string) => void`	none	Called with the new value when a segment is selected.	Yes
`size`	`"sm" \| "md" \| "lg"`	`md`	Size token.	No
`ariaLabel`	`string`	none	Accessible name for the group (required; announced by screen readers).	Yes
`className`	`string`	none	Additional CSS class names.	No

Variants

Available sizes: sm, md, lg (default md).

Invalid combinations

The contract records no invalid combinations.

Keyboard

SegmentedControl keyboard behaviour
Key	Behaviour
Tab	Moves focus to the selected segment (roving tabindex)
Arrow Left/Up and Right/Down	Move selection to the previous/next enabled segment.
Home/End	Select the first/last enabled segment.

Rules

Every item under When not to use is a MUST NOT. MUST and SHOULD follow RFC 2119.

SegmentedControl rules
Level	Rule	How it is checked
MUST	ARIA: Container is role=radiogroup with a required aria-label.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	ARIA: Each segment is role=radio with aria-checked reflecting selection.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	ARIA: Disabled segments are skipped by keyboard navigation.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	Required stories produce no axe violations at the configured severity.	Automated by `npm run test:stories:matrix:ci`. WCAG 2.5.8.
MUST	The accessibility tree (role, name, state) matches the committed snapshot for every required story.	Automated by `npm run test:stories:matrix:ci`. WCAG 1.3.1, 4.1.2.
MUST	The component remains legible and operable under a real browser forced-colors: active pass.	Automated by `npm run test:stories:hc`.
MUST	Every documented keyboard interaction works as specified.	Not yet verified: no evidence record. WCAG 2.1.1, 2.1.2.
MUST	A human completed an end-to-end accessibility review of this component.	Manual review, last on 2026-07-12.

Install and import

Install: npm install @digitaltableteur/react (version 0.9.1, restricted access on npm).
Import: import { SegmentedControl } from "@digitaltableteur/react";
Entry point: @digitaltableteur/react/navigation exports it too.
Styles: import @digitaltableteur/react/style.css once at the app boundary.
Also available as the custom element <dt-segmented-control>; see the custom elements manifest.