Segment
FreeA compact switch between a few views or values of the same content, such as a period, a layout or a billing interval.
npx wunderui-cli add segmentPlayground
Installation
npx wunderui-cli add segmentWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import { Segment } from "@/components/ui/segment"
import type {
SegmentOption,
SegmentShape,
SegmentSize,
} from "@/components/ui/segment"Then use it:
import { useState } from "react"
import { Segment } from "@/components/ui/segment"
export function Range() {
const [range, setRange] = useState("week")
return (
<Segment
aria-label="Time range"
value={range}
onValueChange={setRange}
options={[
{ value: "day", label: "Day" },
{ value: "week", label: "Week" },
{ value: "month", label: "Month" },
]}
/>
)
}Expected result: You see a grey pill-shaped bar with Day, Week and Month, with Week selected in white. Click Month or arrow to it and the fill moves there.
When to use
Use Segment for
- Switching the view or scope of one piece of content: a period, a layout, a billing interval
- A choice between two to five short options that are all visible at once
- A control in a card, chart or table header that changes what is shown below it
Use something else for
- Tabs for separate panels of content, each with its own heading or URL
- Toggle for a single option that is on or off
- Radio Button Group for one choice in a form that is submitted with the rest of the fields
- Checkbox Button Group for a choice of several options at once
Content
An option holds a label, an icon with a label, or an icon only. An icon-only option needs a visually hidden label, since it has no other accessible name.
Width
The track is as wide as its options. To make it fill its row, make the track full width and let every option grow.
Options
Two to five options with short labels fit a phone. The track does not scroll or wrap, so five long labels such as Quarter and Year are wider than a 320 px screen.
Motion
With the slide option the selected pill glides to the next option. Without it the selection switches at once, and with reduced motion the pill never moves.
Activation
By default the arrow keys move focus and choose at once, like tabs. With manual activation they only move focus and Enter or Space chooses, so a key press cannot trigger something costly.
States
Hover, pressed and focus are real states of every option: point at one, or press Tab and then the arrow keys. A disabled option is dimmed, skipped by the arrow keys and cannot be selected.
Keyboard interactions
The segment is one tab list with a single tab stop on the selected option. Arrow keys move and choose as they go, and with manual activation they only move focus while Enter or Space chooses.
- TaborShift+Tab
- Moves focus into the segment, onto the selected option (or onto the first enabled option when matches none), and out of it again. The other options are not tab stops.
- ArrowRight
- Selects the next enabled option and moves focus to it. From the last option it wraps to the first.
- ArrowLeft
- Selects the previous enabled option and moves focus to it. From the first option it wraps to the last.
- HomeorEnd
- Selects the first or the last enabled option and moves focus to it.
- ArrowRightorArrowLeftorHomeorEnd
- With : only moves focus to the next, previous, first or last enabled option (wrapping). The selection stays on the chosen option until Enter or Space.
- EnterorSpace
- Chooses the focused option, as a click does. With the arrow keys have already chosen it, so you need these only when your refused the change. With this is how a focused option is chosen.
Up and Down do nothing, typing a letter does not jump to an option, and a disabled option is skipped. The rows below describe the default automatic activation.
Behavior and motion
What the segment does with its value, options, sliding pill, screen readers and motion.
- Controlled
- The segment keeps no state of its own, so you pass the value and a change handler. A click or key reports the option's value, and the selection changes when you pass the new value back.
- Options
- Options are an array with a value, a label and optionally an icon or disabled flag, and the label can be any node. Array order is visual order, and the track never wraps or scrolls.
- Badge or counter in an option
- Put a Badge or counter in the label node as the direct, last child of the option, after the label text, such as and a counter. Only then does the option give it the same 4 px from the top, bottom and right edge, and the option's gap to the label. A badge wrapped in another element, or placed before the label, keeps the plain padding and the gaps are uneven.
- Width
- The track is as wide as its options. To fill a row, add a class that makes the track full width and gives each option an equal share.
- Sizes and shapes
- The smallest sizes are 32 and 28 px, and the two largest follow the control tokens: 36 and 40 px at compact density, 40 and 44 px at comfortable. Pill rounds fully, rounded uses 8 px.
- Sliding pill
- With sliding, one pill sits behind the selected option and moves to the next. Until the first paint the selected option fills itself, so server HTML never shows a track without a selection.
- Activation
- Automatic activation moves focus and chooses at once, so the change handler fires on each key press. Manual only moves focus and Enter or Space chooses, which suits choices with a cost.
- Resizing
- The pill follows a resize of the track, such as a wider container or a late font, without sliding. It slides only when the value changes.
- Focus
- Keyboard focus draws the standard focus ring on the option: an indigo border and a 2 px light indigo ring, following the option's radius. The sliding pill stays behind it.
- Assistive technology
- The track is a labelled tab list and each option a tab, but no panels are rendered. Name the content it switches nearby and announce changes in a live region.
- Motion
- The pill moves with a transform, and the text colour and hover fill change quickly.
- Reduced motion
- With reduced motion the pill does not slide. It jumps to the new option, and the selection still changes at once.
Anatomy
The figure marks a two-option segment with sliding: the track, the unselected option, the pill behind the selected one and an icon. Without sliding there is no pill.
- 1data-slot="segment"
The track: a grey bar, as wide as its options, labelled for assistive technology. Size sets its height, and shape sets the corners: a full pill, or 8 px with concentric options.
- 2
One button per entry in the options array, with the selected option as the single tab stop. Hover uses the page fill, pressed the subtle fill, and a disabled option is dimmed and skipped by keys.
- 4Optional
An icon you pass with an option, shown before the label at 14 or 16 px. Give a Lucide icon a 1.5 stroke, and it takes its option's text colour.
- 3data-slot="segment-pill"Optional
The white pill behind the selected option, drawn only when sliding is on, and it moves from the old option to the new one. Without sliding the selected option paints the white fill itself.
Best practices
- Do
Keep it to two to five options with short labels. The track does not wrap or scroll, so five long labels are wider than a phone.
- Do
Pass an aria-label, for example Time range. It names the tab list, and the options only carry their own labels.
- Do
Give an icon-only option a visually hidden label such as List. Without it the option has no accessible name.
- Do
Pick the size by place: the smaller ones inside a card or chart header, the larger ones to line up with a Button. Those heights follow the density tokens.
- Do
Turn on sliding when the options are neighbours the eye should follow, such as a period. Use the plain version for a control that changes rarely.
- Don’t
Don't pass a value that matches no option. The first enabled option becomes the tab stop, but none looks selected.
- Don’t
Don't use a Segment to open panels with their own content and URL, because it renders no panels. Tabs owns the panels.
- Do
Switch to manual activation when a choice is hard to undo or costly, such as a permission level or billing interval. Keep the default when choosing only changes a view.
API reference
Segment is a plain component, so the table lists every prop. The entries of the options array are described under options.
The track: a grey bar, as wide as its options, labelled for assistive technology. Size sets its height, and shape sets the corners: a full pill, or 8 px with concentric options.
| Prop | Type | Default | Description |
|---|---|---|---|
| options required | SegmentOption[] | — | The options in the order they are shown: . is a unique string, any node, an element drawn before the label (a Lucide icon with ), dims the option and removes it from the keys. |
| value required | string | — | The of the selected option. Required: the segment is controlled. A value that matches no option leaves nothing selected and makes the first enabled option the tab stop. |
| onValueChange required | (value) => void | — | Called with the of an option when it is clicked or reached with an arrow key, Home or End. Store it and pass it back as . |
| size | "lg" | "sm" | "xs" | "md" | "md" | (32 px, chart filters), (28 px), (the default, the Button height) or . and follow the density tokens. |
| shape | "rounded" | "pill" | "pill" | (the default) rounds the track and the options fully. gives the track 8 px corners and the options a concentric radius. |
| slide | boolean | true | Slides the selected pill to the next option with a transform instead of switching at once. On by default; pass to switch at once. It does not slide when the user prefers reduced motion. |
| activation | "auto" | "manual" | "auto" | What the arrow keys, Home and End do. (default) moves focus and chooses the option at once. only moves focus; Enter or Space chooses. Mouse and touch are unaffected. |
| aria-label | string | — | Names the tab list for screen readers, for example . Pass it every time: the options only carry their own labels. |
| className | string | — | Extra classes for the track, for example the classes that make it fill its row. |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("segment")npx wunderui-cli add segmentThe full library index for assistants is at /llms.txt.