# Segment Group (/docs/segment-group)
`SegmentGroup` is a compact, always-visible single-choice control — a row (or column) of mutually exclusive segments with a pill that slides to the selected item. Reach for it over a [`Select`](/docs/select) when the option set is small (2–5 items) and you want every choice visible at a glance: view toggles, filters, billing cadence, alignment. It implements the kit's value-based form-control contract, so `name` submits and `onChange` hands you the value directly. Label, description, and error are built in via [`Field`](/docs/field).
```tsx
import { SegmentGroup } from "@42-central/ui-react/segment-group";
;
```
## Playground [#playground]
## Items [#items]
`data` accepts bare strings (where the value *is* the label) or
`{ value, label, disabled? }` objects — mixed freely.
```tsx
// 1 — strings (value === label)
// 2 — objects, with optional per-item disabled
```
Each item also accepts an optional `testId`, defaulting to `` `item-${value}` `` — see the [Testing](/docs/testing) guide.
## Variants [#variants]
Five treatments, mirroring [`Button`](/docs/button). The variant restyles all three layers — the tray, the sliding pill, and the checked label — off the same `--c-*` color slots, so they all swap palettes uniformly. `filled` is a solid pill, `light` a soft tint, `outline` a ringed pill over the track, `subtle` is chromeless. `default` is the same solid pill as `filled` on a lighter tray — with no `color` set it resolves to black (white in dark theme), and it tints like every other variant when you give it one, whether that comes from the group `color` or a [per-item color](#per-item-color).
## Sizes [#sizes]
Five sizes — `xs` through `xl` — matching the rest of the family.
### Composing with Input [#composing-with-input]
Every size matches `Input` / `NumberInput`'s exact box height, so a `SegmentGroup` sits flush inline next to one of the same size — [`TimeInput`](/docs/time-input)'s AM/PM toggle is exactly this case.
## Colors [#colors]
The resting segments are palette-independent; only the sliding pill (and the checked label's text) adopt `color`. Set `data-color` once on the root and every kit palette tints for free.
## Per-item color [#per-item-color]
Give an item its own `color` and the pill adopts it whenever that item is selected — handy for status pickers where each option owns a hue. This overrides the group `color` for that segment, on every variant including `default`; the checked label follows the pill onto `--c-on-solid`, so it stays legible in each item's palette. Select each segment below to see the pill shift.
## Custom rendering [#custom-rendering]
By default each segment renders its `label`. Pass `renderItem` to fill the label content yourself — it receives the (value-narrowed) `item`, including its typed [`payload`](#typed-payload), and the live `{ checked, disabled }` state. The segment keeps its sizing, sliding pill, and selection wiring; you fill the inside. Define the function in a `"use client"` module so it survives the server → client boundary.
```tsx
"use client";
// item.payload is inferred from `data` — here { count: number } | undefined
const renderTab = (item, { checked }) => (
{item.label}
{item.payload && (
{item.payload.count}
)}
);
;
```
### Typed payload [#typed-payload]
`SegmentGroup` is generic over `data` (via a `const` type parameter), exactly like [`Select`](/docs/select#typed-payload): `value` / `onChange` narrow to the literal value union, and an item's `payload` is inferred so `item.payload` is fully typed in `renderItem` (and `undefined` for bare-string or payload-less items). The machine ignores `payload` — only your renderer sees it.
```tsx
"use client";
const evals = [
{ value: "all", label: "All", payload: { count: 128 } },
{ value: "booked", label: "Booked", payload: { count: 9 } },
] as const;
// value is 'all' | 'booked'; item.payload is { count: number } | undefined
console.log(value)}
renderItem={(item) => (
<>
{item.label} ({item.payload?.count})
)}
/>;
```
## Orientation [#orientation]
Set `orientation="vertical"` to stack the segments in a column instead of a row.
## Label, description & error [#label-description--error]
`SegmentGroup` wraps itself in [`Field`](/docs/field), so `label` / `description` / `error` / `required` work out of the box and wire the `aria-*` relationships. Passing `error` flips the control to the invalid (red) state.
## Controlled [#controlled]
Drive the value from state. `onChange` hands you the selected value directly.
```tsx
"use client";
import { useState } from "react";
import { SegmentGroup } from "@42-central/ui-react/segment-group";
export function ViewToggle() {
const [view, setView] = useState("list");
return (
);
}
```
## Forms [#forms]
`SegmentGroup` renders a hidden radio input per segment, all sharing the field `name`, so the selected value rides a native `
```
## API [#api]
## Accessibility [#accessibility]
* Built on Ark UI's SegmentGroup (radio-group) machine: `←` / `→` (or `↑` / `↓` when vertical) move and select, `Tab` enters / leaves the group, and the selection follows focus.
* Each segment is backed by a hidden native radio input with the shared `name`, exposing `role="radiogroup"` / `radio` and `aria-checked`.
* `invalid` (or `error`) flips the group to the red state; label / description / error associations are wired via the built-in `Field`.
* RTL is honored via the document `dir` — the segments and the sliding pill mirror automatically.
For options that should look like buttons (icons, per-item colors, toolbars), or for several selected values at once, see [`ButtonSelect`](/docs/button-select) and [`ButtonMultiSelect`](/docs/button-multi-select).