Components / Controls

SegmentedControl

A compact single choice for view switchers and modes, such as Tree or Raw. Segments sit side by side and exactly one is active. For a longer list of options use RadioGroup or Select.

Source Edit this page

Arrow keys select

When to use

Switching how the same content is shown (Tree / Raw, List / Grid).
A small set of modes where all options should stay visible.
Icon-only switches in toolbars, such as ThemeToggle.

Use something else when:

options need descriptions or there are many: RadioGroup or Select
it is one on/off setting: Switch
it navigates between pages: Link

Usage

tsx

import { SegmentedControl } from "@arshad-shah/cynosure";
import { code, tree } from "@arshad-shah/cynosure/icons";

<SegmentedControl
  label="View"
  defaultValue="tree"
  onChange={setView}
  options={[
    { value: "tree", label: "Tree", icon: tree },
    { value: "raw", label: "Raw", icon: code },
  ]}
/>

label names the group for assistive technology. Use value and onChange(value) for controlled state, or defaultValue for uncontrolled.

Icon-only segments

With iconOnly, only the icons show. Each option's label stays as its accessible name, so it is still required.

Icon only segments are named

Options

fullWidth: stretches the control to fill its container.
size: xs, sm, md or lg. xs is 20px with smaller text and icons, matching the xs Button, for dense desktop chrome. Each segment is still 24px to press, and 44px on coarse pointers through an invisible hit area, so an xs control keeps its look on touch screens.
tone: colours the active segment's content (default neutral).
disabled: on the control or on a single option.

Props

Every prop of SegmentedControl
Prop	What it does	Type	Default
`label`Required	Accessible name of the group.	`string`
`options`Required	The segments: `{ value, label, icon?, disabled? }`.	`SegmentOption[]`
`name`	Submits the value with its form under this name. Two controls may share a name and stay independent.	`string`
`value`	Controlled selected value.	`string`
`defaultValue`	Selected value at first, when uncontrolled.	`string`
`onChange`	Called with the segment's value when it is chosen.	`((value: string) => void)`
`iconOnly`	Show icons only; labels stay as accessible names.	`boolean`
`fullWidth`	Stretch to the full width of the container.	`boolean`
`disabled`	Disables every segment; the value is not submitted.	`boolean`
`size`	Height and text size of the segments. Default "md". `xs` (about 20px) is for dense desktop chrome: each segment is still 24px to press (44px on coarse pointers).	`DenseSize`	`"md"`
`tone`	Colour of the active segment's content.	`Tone`
`className`	Added to the root element, for layout.	`string`
`style`	Layout only.	`CSSProperties`

Generated from the type definitions in @arshad-shah/cynosure 0.5.0.

Behaviour and accessibility

Behaviour and accessibility, table 1
Input	Result
`TabTab`	Moves focus into the group
Arrow keys	Move and select the next or previous segment
Click, tap	Selects the segment

Native radios: the control is a radiogroup of native radios, so forms and reset work.
No duplicate events: activating the current segment again never fires onChange.
Names: every segment is named by its label, including icon-only ones.

Touch

On coarse pointers (phones and tablets) segments grow to a larger hit area without changing the visible layout.

Theming

Tokens: --cy-segmented-control-{radius,track-bg,active-bg,padding}; an xs control is --cy-control-height-xs tall.

createTheme({ components: { segmentedControl: { radius: "999px", padding: "3px" } } });

ThemeToggle · RadioGroup · Select · Toolbar

These examples run Cynosure 0.5.0 (commit 50ce30b), the version on npm.

When to useLink to "When to use"

UsageLink to "Usage"

Icon-only segmentsLink to "Icon-only segments"

OptionsLink to "Options"

PropsLink to "Props"

Behaviour and accessibilityLink to "Behaviour and accessibility"

TouchLink to "Touch"

ThemingLink to "Theming"

RelatedLink to "Related"