Segmented Control
Last Updated: September 2026Segmented controls let users choose one option from a short, joined set — ideal for view switchers and compact filters.
Source CodeAnatomy
link- 1Root
- 2Button
- 3Pressed segment
- 4Track
Variants
linkButtons
Text segments for labeled options.
Icon buttons
Icon-only segments for dense toolbars — aria-label is required.
Stretch
stretch fills the container; segments share width equally.
Disabled segment
Disable individual SegmentedControl.Button items.
Sizes
linkSegmented controls support 3 sizes: S, M, and L.
Usage Guidelines
linkWhen to use
- •For exclusive choices in a compact toolbar or filter row.
- •When options are short and benefit from a joined segmented look.
- •For view switchers (day/week/month) and similar mode toggles.
When not to use
- •For independent on/off toggles — use Toggle Button or Switch.
- •For long labels or many options — use Select.
- •For primary page actions — use Button.
Keep segment labels short and parallel (Day / Week / Month).
Don't put long sentences or wrapping prose in segment labels.
Always set aria-label on IconButton segments.
Don't use segments for independent on/off settings — use Toggle Button.
Behaviors
linkValue model
- •defaultValue and value are arrays of strings (e.g. defaultValue={["day"]}).
- •Each Button / IconButton needs a unique value string.
- •Uncontrolled: defaultValue; controlled: value + onValueChange from ToggleGroup.
Layout
- •size: sm | md | lg — controls height, radius, and horizontal padding.
- •stretch: true makes the root full width and grows each segment equally.
- •Without stretch, the control is width-fit around its segments.
Parts
- •SegmentedControl.Button for labeled segments.
- •SegmentedControl.IconButton requires value, icon, and aria-label.
- •disabled on a child skips that option without disabling the whole group.
Content Guidelines
linkLabels
- •Use short nouns or view names users already know (Day, List, Grid).
- •Match casing across segments — Title Case or sentence case, not mixed.
Values
- •Use stable slug values ("day", "list"), not display labels.
- •Keep demo values synthetic — no site names or patient identifiers.
Accessibility
linkText & Labels
- •Text buttons get their accessible name from children.
- •IconButton requires aria-label — icons alone are not enough.
ARIA attributes
- •Built on Base UI ToggleGroup + Toggle.
- •Pressed segments expose pressed state; disabled segments are not selectable.
Keyboard Support
- •Tab → move focus into the group / between focusable segments.
- •Enter / Space → press the focused segment.
- •Arrow keys may move focus between toggles depending on Base UI group behavior.
WCAG Compliance Standards
FAQs
linkWhy is defaultValue an array?
SegmentedControl wraps Base UI ToggleGroup, which models selection as string[]. For exclusive mode pass a single-item array such as defaultValue={["day"]}.
Button vs IconButton?
Use Button for visible text labels. Use IconButton when space is tight — it requires icon, value, and aria-label.
SegmentedControl vs Tab Menu?
SegmentedControl switches modes/filters in place. Tab Menu navigates between destinations or major content panes.