# Segment group

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.

- Registry name: `segment-group` (`@candor/segment-group`)
- Tier: Pro. Installing it needs a Pro, Premium or Team licence key: the person runs `npx candor-ui key <key>` themselves; never ask for the key in chat or write it to a file.
- Docs: https://candor.themethodic.com/docs/segment-group

## Install

```bash
npx candor-ui@4 add segment-group
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/segment-group`.
It brings in: locale, locked, merge-refs, tokens, utils.

## Example

```tsx
"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>

Props:

- `segments: readonly Segment<T>[]`: The segments in order.
- `value?: T | null | undefined`: The chosen segment's value; none is chosen when it matches no segment.
- `onValueChange: (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` (default `"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`.

```ts
{
  /** 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;
}
```

## Rules for using Candor UI

- Components take plain typed data. Never pass model output as HTML or render it as a link; messages are typed blocks.
- A control that can't be used says why: wrap it in `<Locked reason="…">`, don't just disable it.
- Don't show a value you don't have: leave it out (it renders as —) rather than guess. An estimate is labelled as one.
- Nothing is pre-selected in a decision a person makes, and the agent is named from your app's data, never from model output.
- Your app's words go in `LocaleProvider`: its fixed strings in `strings`, its nouns in `nouns`; entity kinds and agent roles in `EntityKindsProvider` and `AgentRolesProvider`.
