# SegmentedControl

2–4 visible exclusive options. More than 4 or an unknown count belongs in a Select/Combobox.

Install: `npx candlelight-ds add segmented-control`

Category: primitive · Grammar: G1

## Use when

Switching between a few exclusive views or modes.

## Don't use when

More than 4 options, unknown counts, or navigation.

## States

- selected (fill-active)
- unselected (hover ramp)
- with counts

## Keyboard

- `click/tab` — switches; selection is immediate (optimistic)

## Acceptance tests

- The selected segment sits on fill-active; the rest ride the hover ramp.

## Files

- components/ui/SegmentedControl.tsx

npm dependencies: @candlelight-ds/tokens, clsx, tailwind-merge

Rendered twin: https://candlelight-docs.vercel.app/components/segmented-control · Full spec: https://candlelight-docs.vercel.app/spec.md