Skip to content
Mosaic
On this page

SegmentedControl

A row of mutually exclusive options with a sliding indicator under the selected one. A role='radiogroup' with one tab stop; the arrow keys move and select at once.

Use for

  • switching between a few views or modes, such as monthly and yearly billing
  • a single choice among two to four short options

Practices

GuidancePractice
DoGive the root an accessible name with aria-label or aria-labelledby.
Don’tUse it to switch between panels of content. Use Tabs instead.

API reference

SegmentedControl.Root

Holds the selected value and renders a div with the indicator (cl-segmented-control-indicator). Carries data-disabled. Typed by the value, string by default.

Slot: cl-segmented-control-root

PropTypeDescription
valueValueThe selected value, when controlled.
defaultValueValueThe selected value on mount, when uncontrolled.
onValueChange(value: Value) => voidCalled with the newly selected value.
disabledbooleanDisables every item.Default: false

SegmentedControl.Item

A role='radio' button. Carries data-selected and data-disabled.

Slot: cl-segmented-control-item

PropTypeDescription
valueunknownIdentifies the item, compared with Object.is.
disabledbooleanDisables this item.Default: false

Examples

Billing period

TSX
<SegmentedControl.Root aria-label='Billing period' value={period} onValueChange={setPeriod}>
  <SegmentedControl.Item value='month'>Monthly</SegmentedControl.Item>
  <SegmentedControl.Item value='annual'>Yearly</SegmentedControl.Item>
</SegmentedControl.Root>