A pill segment control switches between two to four related views or filters in the same surface. A pill slides to the active segment.
Every example on this page is the real component, not a picture. Figma: Pill segment control.
Click a segment and the pill slides to it. Large is the page-level switcher; XSmall is for tight toolbars. Below 640px the control fills its parent; from 640px it shrinks to its content.
A pill segment control switches between two to four related views or filters in the same surface. A pill slides to the active segment.
It has four sizes (Large, Medium, Small, XSmall), a black or a white pill, and a track that darkens on hover. It never replaces Tabs (navigation between pages) or Radio buttons (a choice that is submitted).
This documentation has three pages. Examples & Guidelines (this page) shows when and how to use a pill segment control. Specifications holds the values: tokens, sizes, measurements, states and requirements. Code shows how to add one to a page.
Use a pill segment control to switch between two related views or filters in the same surface, for example User roles / Company plan or All features / Key features. Use it to:
A segmented control is for two to four short, related options on one row. It never wraps onto a second row. For more options use eco-select, or eco-radio if all must stay visible.
To move between pages or sections use Tabs. For a choice that is submitted use eco-radio. For a setting that turns on or off use Switch.
The control shows all its segments on one row. Short labels keep it narrow; long labels make it wider than its container.
| The user… | Use |
|---|---|
| switches between 2–4 views or filters of the same content | Pill segment control |
| switches between a few options in a toolbar, joined and framed | Button group |
| moves between pages or sections | Tabs |
| makes a choice that is submitted | eco-radio |
| turns one setting on or off | Switch |
segment-change to swap the content.aria-pressed="true". White text on the black pill.The pill is black by default; use the white pill when the control already sits on a dark or grey surface. Sizes are under Sizes below.
For a control inside another, larger control, on a grey track. The active text stays black.
Four sizes, two to four segments. Large is the page-level view switcher, Medium a view switcher in a drawer, Small secondary filters and XSmall compact filters in a table toolbar. Measurements are under Sizes in Specifications.
Below 640px the control is fluid: it fills its parent and the segments share the space evenly. From 640px it shrinks to its content. Height, padding and text do not change until 769px, so 640–768px still has the mobile size.
A grey track with a black pill and uppercase labels. The pill has a small shadow. Token names and values are under Design Tokens in Specifications.
A click on a segment moves the pill to it, sets aria-pressed and fires a bubbling segment-change event with detail.button. Your page listens for the event and swaps the content.
Hover darkens the track to border-tertiary and underlines the inactive segment. Focus has no style of its own: the buttons use the global keyboard focus ring. All states are listed under States in Specifications.
The pill slides with duration-medium-2 and ease-standard. Try other values under Motion above.
All requirements are listed under Accessibility Requirements in Specifications.
Tab moves between the segments. Enter or Space chooses the focused one. The focus ring shows on keyboard focus only.
The control is a role="group" with an aria-label. Each segment is a button with aria-pressed, so the active one is announced as pressed.