ts
| Guidance | Practices |
|---|---|
| Do | Use for switching between 2–5 mutually exclusive views or modes where all options should be visible. |
| Do | Provide a descriptive label for the control to ensure the group is accessible to screen readers. |
| Don't | Use for page-level navigation — use XDSTabList instead. TabList is a navigation component, while SegmentedControl is an input that always has exactly one selected option. |
| Don't | Use for simple on/off states — use XDSToggleButton instead. ToggleButton can be toggled on or off independently, while SegmentedControl enforces a single selection from a group. |
| Prop | Type | Description |
|---|---|---|
valuerequired | string | The currently selected value (controlled). |
onChangerequired | (value: string) => void | Callback fired when a segment is selected. |
labelrequired | string | Accessible label for the radio group (used as aria-label, never rendered visually). |
childrenrequired | ReactNode | XDSSegmentedControlItem children. |
size | 'sm' | 'md' | 'lg' (default: 'md') | Size variant for the control. |
layout | 'hug' | 'fill' (default: 'hug') | Layout mode. hug (default) sizes segments to content; fill stretches them equally to fill the container. |
isDisabled | boolean (default: false) | Whether the entire control is disabled. |
xstyle | StyleXStyles | StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}. |
| Prop | Type | Description |
|---|---|---|
valuerequired | string | Unique value for this segment, matched against the parent value. |
labelrequired | string | Accessible label for this segment. Rendered as visible text unless isLabelHidden is true. |
isLabelHidden | boolean (default: false) | Whether the label is visually hidden. When true, only the icon is displayed and label is used as aria-label. |
icon | ReactNode | Icon element displayed before the label. |
isDisabled | boolean (default: false) | Whether this individual item is disabled. |