Pick exactly one of a few short options (a period or a view) on a grey track with a sliding white thumb.
Default
Pick one period; the white thumb slides to it. Arrow keys move and select.
Installation
Copies the component into src/design-system/ as your own source, with only the files it needs.
npx avesk-ui@latest add segmented-controlBrings the 1 file it builds on (icon.tsx). The first time, it also adds the tokens and the cn() helper, imports the tokens in globals.css and installs clsx and tailwind-merge. Files already in your project are kept unless you add --force.
Import
Lives in src/design-system/components/segmented-control.tsx.
import { SegmentedControl } from "@/design-system/components/segmented-control";Usage
<SegmentedControl
aria-label="Reporting period"
value={period}
onValueChange={setPeriod}
options={[
{ id: "weekly", label: "Weekly" },
{ id: "monthly", label: "Monthly" },
{ id: "yearly", label: "Yearly" },
]}
/>Examples
With icons
A leading icon helps when the options are views of the same data.
Sizes
sm (24px items) for toolbars and card headers, md (28px, the default) everywhere else.
Full width
fullWidth stretches the track and shares the width equally, e.g. across a card.
Invoices
Controlled
Hold the value in state with value and onValueChange when other UI depends on it.
Showing monthly revenue for Denzing.
When to use
Use it when
- Switching between 2–5 short, mutually exclusive periods or views: Weekly / Monthly / Yearly, List / Board
- A compact choice in a toolbar or card header that changes what is shown right away
Don’t use it when
- Filtering a list where each option shows a count → Filter pills
- Switching between sections of a page → Tabs
- Choosing one of several options in a form → Radio or Choice chip
Rules
- 2–5 options with one- or two-word labels; one is always selected
- Use size sm in toolbars and card headers, md (default) elsewhere
- Icons only lead a label (color="current"); never icon-only without a label
- fullWidth inside narrow containers such as cards and side panels
Properties
SegmentedControl
| Prop | Type | Default |
|---|---|---|
aria-label * | string | – |
options * | SegmentedControlOption<T>[] | – |
value | T | – |
defaultValue | T | – |
onValueChange | (id: T) => void | – |
size | "sm" | "md" | "md" |
fullWidth | boolean | false |
className | string | – |
* required
Accessibility
- role="radiogroup" with aria-label; items are role="radio" with aria-checked
- Roving tabindex: only the selected item is tabbable; arrows move and select (wrapping, skipping disabled), Home/End jump to the ends
- The sliding thumb is aria-hidden and its motion is off under prefers-reduced-motion