SegmentedControl is a radio group with joined options. Use it for a short, mutually exclusive choice. For navigation between content panels, use Tabs.
Usage
Supply an accessible group name witharia-label or aria-labelledby. Each option needs a unique string value. Selection belongs to the group; options do not have independent checked state.
Uncontrolled state
defaultValue initializes selection. The group owns later changes. Add onValueChange if you need to observe them without controlling the value.
Controlled state
value in application state and update it in onValueChange. Do not combine value and defaultValue or switch ownership modes after mounting.
Icon options
aria-label. startIcon is decorative and hidden from assistive technology. Options with visible text use label and may also provide startIcon. Set disabled on an option to prevent its selection, or on the group to disable every option.
Keyboard, forms, and direction
Tab enters the group; arrow keys move between enabled options and update selection.itemWidth="equal" is the default; use content when labels should determine widths. Set name to include the selected value in native form submission.
For right-to-left content, pair TextDirectionProvider with a matching dir attribute. The provider controls directional interaction; dir controls the document layout.
Props
string
required
Accessible group name. Supply this or
aria-labelledby.string
required
ID of an element that labels the group. Supply this or
aria-label.string | ((state: RadioGroupState) => string | undefined)
CSS class applied to the element, or a function that
returns a class based on the component’s state.
string
The uncontrolled value of the radio button that should be initially selected.To render a controlled radio group, use the
value prop instead.boolean
default:"false"
Whether the component should ignore user interaction.
string
Identifies the form that owns the radio inputs.
Useful when the radio group is rendered outside the form.
Ref<HTMLInputElement>
A ref to access the hidden input element.
"content" | "equal"
default:"equal"
Use equal-width options or size each option to its content.
string
Identifies the field when a form is submitted.
((value: TValue, eventDetails: { reason: "none"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void)
Callback fired when the value changes.
readonly SegmentedControlOption<TValue>[]
required
Options with a unique string
value, a label or startIcon, and optional disabled. Icon-only options require an aria-label.boolean
default:"false"
Whether the user should be unable to select a different radio button in the group.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, RadioGroupState>
Allows you to replace the component’s HTML element
with a different tag, or compose it with another component.Accepts a
ReactElement or a function that returns the element to render.boolean
default:"false"
Whether the user must choose a value before submitting a form.
CSSProperties | ((state: RadioGroupState) => CSSProperties | undefined)
Style applied to the element, or a function that
returns a style object based on the component’s state.
string
The controlled value of the radio item that should be currently selected.To render an uncontrolled radio group, use the
defaultValue prop instead.