Skip to content
Tier

Segment group

Pro

A 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.

Markdown

Preview

Loading the preview

Install

With the Candor CLI

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

TSX · The example above
"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>

PropTypeDefaultDescription
segmentsrequiredreadonly Segment<T>[]—The segments in order.
valueT | 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`.
classNamestring | undefined—Classes for the track, merged with Candor's.
segmentClassNamestring | undefined—Classes for every segment, merged with Candor's.
refReact.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; }