SegmentedControl

SegmentedControl is a compound component for short, always-visible exclusive option sets, with item-level native radio inputs and an animated selected-state indicator.

Storybook Source Figma

Root Props

Prop	Type	Default
`disabled`	`boolean`	—
Disables all segments, preventing user interaction.
`size`	`SegmentedControlSize`	`'md'`
Visual size of the segmented control.
`variant`	`SegmentedControlVariant`	`'secondary'`
Visual style variant of the segmented control.
`ref`	`Ref<HTMLDivElement>`	—
Ref to the root container element. Useful for measuring or controlling focus.
`value`	`SegmentedControlValue`	—
The currently selected value of the segmented control
`defaultValue`	`SegmentedControlValue`	`''`
The initial selected value when the component is used in an uncontrolled mode
`onChange`	`(e: ChangeEvent<HTMLInputElement>) => void`	—
Fired when the selected segment changes. This event mirrors the native `change` event of a radio input and can be used to integrate with forms or listen for user selection. The event target is the underlying hidden `<input type="radio">`.
`name`required	`string`	—
The name of the underlying radio group. All `SegmentedControlItemInput` elements share this name, allowing the segmented control to behave as a single native radio group for form submission and accessibility.

Also accepts all <div> attributes.

Child Parts

SegmentedControlItem: visible selectable segment.
SegmentedControlIndicator: animated selected-state surface.
SegmentedControlItemInput: native radio input for each item.

`SegmentedControlItem`

Prop	Type	Default
`disabled`	`boolean`	—
Disables the item, preventing selection and focus.
`size`	`SegmentedControlSize`	—
Controls the size of the item. Affects padding, font size, and spacing.
`variant`	`SegmentedControlVariant`	—
Visual style variant of the item.
`value`required	`SegmentedControlValue`	—
The unique value associated with this segment
`ref`	`Ref<HTMLLabelElement>`	—
Ref forwarded to the underlying `<label>` element.

Also accepts all <label> attributes.

`SegmentedControlIndicator`

Also accepts all <div> attributes.

`SegmentedControlItemInput`

Also accepts all <input> attributes.

Types

SegmentedControlProps
SegmentedControlItemProps
SegmentedControlIndicatorProps
SegmentedControlItemInputProps
SegmentedControlSize
SegmentedControlVariant

State Model

SegmentedControl can be uncontrolled through defaultValue or controlled through value and onChange.
In uncontrolled mode the native radio group owns the selection: clicks, keyboard, form reset and programmatic checked changes all apply without React state.
SegmentedControlIndicator is anchored to the checked segment in CSS, so it follows any of those changes.
useSegmentedControlContext is available for advanced wrappers and custom compositions.