Segmented control
A segmented control switches between views of the same content, such as List and Grid. One segment is always on, and the change applies at once.
<tk-segmented-control label="View" value="list"> <tk-segment value="list">List</tk-segment> <tk-segment value="grid">Grid</tk-segment> <tk-segment value="map">Map</tk-segment> </tk-segmented-control>
Anatomy
| Part | What it is |
|---|---|
tk-segmented-control |
the track: a sunken bed, 32px tall; one Tab stop |
tk-segment |
one option; all segments are the same width |
| selected chip | a raised chip with a shadow behind the selected segment |
Shape
shape="round" makes the track and the chip pills.
<tk-segmented-control label="Period" value="week" shape="round"> <tk-segment value="day">Day</tk-segment> <tk-segment value="week">Week</tk-segment> <tk-segment value="month">Month</tk-segment> </tk-segmented-control>
States
<tk-segmented-control label="Messages" value="all"> <tk-segment value="all">All</tk-segment> <tk-segment value="unread">Unread</tk-segment> <tk-segment value="flagged" disabled>Flagged</tk-segment> </tk-segmented-control> <tk-segmented-control label="Layout" value="grid" disabled> <tk-segment value="list">List</tk-segment> <tk-segment value="grid">Grid</tk-segment> </tk-segmented-control>
Hover darkens a segment's label, press tints it, and keyboard focus shows a ring.
disabledon a segment: it's dimmed, can't be clicked, and the arrow keys skip it.disabledon the control: the whole control leaves the Tab order. The selected chip stays visible, so people still see the current view.
When to use
- Use a segmented control to change how one piece of content is shown: List or Grid, Day, Week or Month, All or Unread.
- Use a
Tab bar to move between sections with different content. - Use a
Radio group for a value that a form submits. A segmented control is never part of a form. - Use a
Select for more than 5 options or for long labels. - Use a
Toggle button group when more than one option can be on.
Content
- Use 2 to 5 segments, each one short word in sentence case.
- Name the view, not the action: "Grid", not "Show grid".
- Give the control a
labelthat says what it switches: "View", "Period".
Do / Don't
| ✅ Do | ❌ Don't |
|---|---|
| Switch views of the same content | Move between sections; use a tab bar |
| Keep exactly one segment on | Let several be on; use a toggle button group |
| Show 2 to 5 one-word segments | Squeeze in 6 options or long labels; use a select |
| Apply the change at once | Put it in a form; use a radio group |
Listen for change on the control |
Add a click handler to each segment |
Related
Tab bar : moves between sections of content.Toggle button group : the same joined row, but several options can be on.Radio group : one choice that a form submits.Switch : one setting, on or off.
API
tk-segmented-control
| Attribute | Type | Default | What it does |
|---|---|---|---|
value |
string | '' |
the selected segment's value; updates when someone picks a segment |
label |
string | — | the group's accessible name; required |
disabled |
boolean | false |
disables every segment |
shape |
rect | round |
rect |
rounded corners or a pill |
| Slot | Content |
|---|---|
| default | 2 to 5 tk-segment elements |
tk-segment
| Attribute | Type | Default | What it does |
|---|---|---|---|
value |
string | '' |
the segment's identity; required |
disabled |
boolean | false |
dimmed, not clickable, skipped by the arrow keys |
| Slot | Content |
|---|---|
| default | the label, one short word |
Events
change fires on tk-segmented-control when someone picks a different segment. Read the
new value. It doesn't fire when you set value in code, or when the segment is already
selected.
Tokens
| Part | Tokens |
|---|---|
| track | surface/sunken, radius-8, space-2 padding |
| segment | text/secondary, Label Medium (14/20), space-12 padding-inline |
| segment, hover | text/default |
| segment, press | state/press |
| selected chip | surface/raised + shadow-1 + text/default, radius-6 |
| disabled | text/disabled |
| focus ring | border/accent/focus |
With shape="round", the track and the chip use radius-full. Values per theme:
Accessibility
Built in:
- The control is a radio group named by
label; each segment is a radio with its checked state. - One Tab stop: Tab lands on the selected segment.
- The arrow keys move focus and selection together, like native radio buttons.
- The selected segment is marked by its raised chip, not by color alone.
Your part:
- Set
labelon the control andvalueon every segment. - Update the content as soon as
changefires. If it takes time to load, show aSpinner in the content; keep the control usable.
| Key | Action |
|---|---|
Tab |
moves focus to the selected segment, then out of the control |
Right / Down |
selects the next segment; wraps to the first |
Left / Up |
selects the previous segment; wraps to the last |
Space |
selects the focused segment |