SegmentedControl

A single-select, always-one-selected control that switches between a small set of visible options — a view or mode switcher rendered as a pill of segments. Built on Radix ToggleGroup (type="single") but kept permanently selected: re-clicking the active segment never clears it. Compose it from {@link SegmentedControlItem}s; shared size / fullWidth / active state flow to them through context. Controlled via value, or uncontrolled via defaultValue. Items scroll horizontally with a trailing fade hint when they overflow.

Usage

import { SegmentedControl, segmentedControlAnatomy, SegmentedControlItem, SegmentedControlItemProps, SegmentedControlProps } from "@desk/ui/components/segmented-control";

Best practices

One value is always selected — the active segment cannot be deselected; for deselectable or multi-select sets reach for ToggleGroup.
Switching visible content panels is Tabs; navigating URLs is TabNavigation — SegmentedControl is an input that selects a value or mode.
Icon-only items must carry an aria-label.

Props

SegmentedControl

Prop	Type	Default	Description
value	`T`		Controlled selected value.
defaultValue	`T`		Uncontrolled initial value.
onValueChange	`(value: T) => void`		Fires with the newly selected value — never with "".
size	`ResponsiveValue<"base" \| "2xs" \| "xs" \| "sm" \| "lg" \| "xl" \| "2xl" \| "3xl">`	`"sm"`
fullWidth	`boolean`	`false`

SegmentedControlItem

Prop	Type	Description
count	`number`	Optional trailing count, muted and tabular.
dot	`string`	Status dot color (CSS color value) rendered before the label.
icon	`LucideIcon \| ComponentType<SVGProps<SVGSVGElement>>`	Leading icon; icon-only items must supply `aria-label` (dev-warned otherwise).

Also exports

constsegmentedControlAnatomy
interfaceSegmentedControlItemProps
typeSegmentedControlProps

Anatomy

SegmentedControl

segmented-control

Single-select mode / value switcher

SegmentedControlItem

segmented-control-item

A single selectable segment

SegmentedControlIndicator

segmented-control-indicator

Animated pill that slides to the active segment

Composition

Builds on

Dot, Icon, ScrollArea, ScrollFade, Segmented

Used by

ColorPalette, ToggleGroup