Segment group
ProA small set of choices drawn as one control: a muted track of segments, the chosen one raised as a card. For a kind or status filter over a list, a view switch, a setting with a few values. It is a radio group: one Tab stop (the chosen segment, or the first when none is), with Left and Right (swapped in a right-to-left page), Up and Down, Home and End moving between the segments. For a filter or a view they choose as they go, so moving is choosing; for a setting the app saves, activation="manual" has them move focus only, and Space, Enter or a press chooses. Each segment is a button. A segment that can't be chosen says why: it is marked aria-disabled with its reason and refuses the press, and the arrow keys, Home and End still move focus onto it, so its reason shows, without choosing it; the Tab stop stays on the chosen segment. A segment in focus has a ring in the marks colour; in forced colours, an outline in the system's Highlight, doubled on the chosen segment so the focus and the choice both show.
The labels are the app's: give the group its name (aria-label or aria-labelledby) and each segment its words.
Preview
Loading the preview
Install
First time? Get started sets up the registry and theme. Or with shadcn directly: npx shadcn@latest add @candor/segment-group
Brings in: locale, locked, merge-refs, tokens, utils
Usage
"use client"
import * as React from "react"
import { SegmentGroup } from "@/components/candor/segment-group"
type Show = "all" | "failed" | "running" | "archived"
// A status filter over a list: one Tab stop, the arrow keys move the choice, and a segment that can't be chosen says why.
export default function Example() {
const [show, setShow] = React.useState<Show>("all")
return (
<div className="flex flex-col gap-2">
<SegmentGroup
aria-label="Show"
className="w-fit text-xs"
value={show}
onValueChange={setShow}
segments={[
{ value: "all", label: "All 42" },
{ value: "failed", label: "Failed 3" },
{ value: "running", label: "Running 5" },
{ value: "archived", label: "Archived", locked: "Archived runs are on the Team plan" },
]}
/>
<p className="text-sm text-muted-foreground">Showing: {show}</p>
</div>
)
}<SegmentGroup>
| Prop | Type | Default | Description |
|---|---|---|---|
| segmentsrequired | readonly Segment<T>[] | — | The segments in order. |
| value | T | null | undefined | — | The chosen segment's value; none is chosen when it matches no segment. |
| onValueChangerequired | (value: T) => void | — | Called with a segment's value when the person presses it (or presses Space or Enter on it), and, unless `activation` is `"manual"`, when they move to it with the arrow keys, Home or End. |
| activation | "automatic" | "manual" | undefined | "automatic" | When the keys choose. `"automatic"` (the default): the arrow keys, Home and End choose the segment they move to, for a filter or a view switch, where each step shows its result. `"manual"`: they move focus only, and Space, Enter or a press chooses, for a setting the app saves or that takes effect, so passing over a value doesn't set it. While the person moves, the Tab stop follows focus; when focus leaves the group it goes back to the chosen segment. |
| "aria-label" | string | undefined | — | The group's name, read before its segments. |
| "aria-labelledby" | string | undefined | — | The id of the element that names the group, in place of `aria-label`. |
| className | string | undefined | — | Classes for the track, merged with Candor's. |
| segmentClassName | string | undefined | — | Classes for every segment, merged with Candor's. |
| ref | React.Ref<HTMLDivElement> | undefined | — | The track element. |
Types
- Segment
- One segment of a `SegmentGroup`.
{ /** What choosing it sets: the value `onValueChange` is called with. */ value: T; /** What the segment shows: a word, a word and a count, or an icon (then give it a `name`). */ label: React.ReactNode; /** The segment's accessible name, when its label doesn't say it in words (an icon). */ name?: string | undefined; /** A hint shown when the pointer rests on the segment. */ title?: string | undefined; /** * Why the segment can't be chosen. It stays focusable, is marked `aria-disabled`, refuses the press and gives the * reason (`Locked`). The arrow keys, Home and End move focus onto it, so its reason shows, but don't choose it. */ locked?: string | null | undefined; /** Classes for this segment alone, merged after `segmentClassName`. */ className?: string | undefined; }