Skip to content
Mosaic
On this page

SegmentedControl

Headless, unstyled single-select row of buttons, one always active. Follows the radio group pattern: role="radiogroup", role="radio" items, one tab stop, and arrow keys that move the selection.

Use for

  • switching between a few mutually exclusive options
  • a billing period toggle, such as monthly or annual
  • a compact single choice shown as buttons instead of radios

Practices

GuidancePractice
DoName the group with aria-label or aria-labelledby on SegmentedControl.Root.
DoSlide SegmentedControl.Indicator with its data-direction, which says whether the selection moved forward or backward.
Don’tUse it when each option owns a panel of content. Use Tabs instead.

API reference

SegmentedControl.Root

A div with role="radiogroup" that holds the selection and arrow-key navigation. Carries data-disabled.

PropTypeDescription
valueValueThe selected value, when controlled.
defaultValueValueThe selected value on mount, when uncontrolled.
onValueChange(value: Value) => voidCalled with the new value. Not called when the same item is chosen again.
disabledbooleanDisables every item.Default: false

SegmentedControl.Item

A button with role="radio" and aria-checked. Carries data-selected and data-disabled. Arrow keys select as they move.

PropTypeDescription
valueunknownIdentifies the option, compared with Object.is. Unique within the root.
disabledbooleanSets aria-disabled. The item stays focusable.

SegmentedControl.Indicator

A decorative span, aria-hidden, for the selection highlight. Carries data-direction.

Examples

Billing period

TSX
<SegmentedControl.Root aria-label='Billing period' defaultValue='monthly'>
  <SegmentedControl.Item value='monthly'>Monthly</SegmentedControl.Item>
  <SegmentedControl.Item value='annual'>Annual</SegmentedControl.Item>
</SegmentedControl.Root>