How to set up SegmentedControl: the sliding selection, tabs versus radio semantics, a non-scrolling row for narrow sidebars, and a second line of description per option.
From @once-ui-system/core 2.8.0, the selected background in SegmentedControl slides between options. This page also covers the props that decide how the control behaves: semantics, scroll and description.
The basic control
A segmented control is a short row of options where exactly one is picked. A period switch on a chart, a status filter above a table, monthly or yearly on a pricing page.Pass value and onChange for a controlled control, or only defaultValue when nothing outside needs to know. If you are porting 1.x code, the old names selected, onToggle and defaultSelected are gone.
The selection slides
In 2.8.0 the selected background no longer jumps to the new option. It slides there. This is on by default, so upgrading is enough.A few things worth knowing:
Reduced motion is respected. Visitors who ask for reduced motion see the selection move without the slide.
compact does not slide. Its joined segments carry their own corners, so the slide is skipped there.
You can turn it off. Set sliding={false} if you want the old jump, for example in a dense toolbar.
Tabs or radio
By default the control is a tab strip for assistive technology: arrow keys move focus, Enter or Space selects. That is right when the options switch between views of the same content.When the options are a setting instead, a choice that gets saved, use semantics="radio". The control becomes a radio group, and the arrow keys move focus and select at the same time, the way native radios do.Either way, name the control with aria-label or aria-labelledby. A row of buttons that says "Day, Week, Month" means nothing to a screen reader without it.
Use
When the options
tabs (default)
Switch the view: a chart period, a table filter
radio
Set a value: billing period, a theme, a saved preference
Narrow spaces
The control scrolls sideways by default, which is fine in a wide header. In a narrow sidebar it is not: two or three options scroll behind a Next button and the last one gets clipped.Set scroll={false} there. The options sit in a plain row that shares the width (equally with fillWidth), and a label that does not fit is truncated instead of hidden.
A second line per option
Each option can take a description, a dimmer line under the label. The option grows to fit both. It works well for a choice that needs one word of context, like a plan or a mode.Keep it to a few words. If an option needs a sentence, it probably wants a radio card or a Select instead.
Check yourself
The control has an aria-label or aria-labelledby
semantics="radio" when the choice is a saved setting
scroll={false} in sidebars and other narrow columns
