Skip to content
Components

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 Base UI ToggleGroup (single-select) 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 "@instruments/materia-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

PropTypeDefaultDescription
classNamestring
valueT

Controlled selected value.

defaultValueT

Uncontrolled initial value.

onValueChange(value: T) => void

Fires with the newly selected value - never with "".

sizeResponsiveValue<"base" | "2xs" | "xs" | "sm" | "lg" | "xl" | "2xl" | "3xl">"sm"
fullWidthbooleanfalse

SegmentedControlItem

PropTypeDefaultDescription
classNamestring
value(required)string

Identifier reported to onValueChange when this segment is selected.

countnumber

Optional trailing count, muted and tabular.

dotstring

Status dot colour (CSS colour value) rendered before the label.

iconLucideIcon | 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, Flex, Icon, ScrollArea, ScrollFade

Used by

ColorPalette