# Combobox

> A select you can type into to filter a long list.

- **Level**: molecule · **Status**: stable · **Role**: input
- **Import**: `import { Combobox, ComboboxContent, ComboboxEmpty, ComboboxGroup, ComboboxInput, ComboboxItem } from "@rrios-forge/ui/molecules/combobox";`
- **Source**: `packages/ui/src/molecules/combobox`

**Purpose.** A searchable single-choice selector. Composes a Popover surface with the cmdk Command primitive — type-ahead filtering, arrow-key navigation, escape-to-close — behind a Trigger that mirrors `Select`'s chrome.

**When to use.**
- The list of options is long (~10 or more) so scanning is slow.
- The user is likely to know the option's name and benefits from filtering as they type.
- The options have grouping (frameworks by family, regions by continent) that filtering can collapse.

**When NOT to use.**
- ≤ 10 options where scanning is fast → use `Select`. Combobox adds keyboard ceremony for no gain.
- Multi-select picker → use a tag-list pattern with `Combobox` + a chips region (or wait for a `MultiCombobox` molecule).
- Free text where any value is acceptable → use `Input`. Combobox enforces a fixed list.

**Composes with.**
- `Field` to inherit label / description / error wiring.
- `Combobox.Trigger / Content / Input / List / Group / Item / Separator / Empty` are the compound surface; consumers always render through them.
- `Label` + `Description` for inline placements outside `Field`.

**Accessibility.**
- The Trigger is a `<button role="combobox" aria-expanded>` with the listbox ID via `aria-controls`.
- The Input inside the popover carries `aria-autocomplete="list"`; the list is `role="listbox"`; items are `role="option"` with `aria-selected`.
- Type-ahead and arrow keys are wired by cmdk. `Escape` closes the popover and returns focus to the Trigger.
- `Empty` is announced inline (no toast) so the user knows their query produced no results.

**Related patterns.**
- `Patterns/Decision Matrix · ComponentChoice` — Combobox vs Select.
- `Patterns/Overlays · OverlayChoice` — Popover-anchored vs Dialog-anchored selection.
- `Patterns/Forms · ChoiceControls` — single-choice vs multi-choice ergonomics.

## Use it for

- Tabs / select / autocomplete → `Tabs` / `Select` / `Combobox` or `SearchField`

## Axes

| Axis | Part | Values | Default | Meaning |
|---|---|---|---|---|
| `size` | — | `sm` `md` `lg` | `md` | Ergonomic scale, in three families (control, text, container). |
| `invalid` | — | `true` `false` | `false` | Fails validation: a danger edge, announced as invalid; pair it with an error message. |

## Stories

- [Playground](/?path=/story/components-molecules-combobox--playground) · frame: `/iframe.html?id=components-molecules-combobox--playground&viewMode=story`
- [Many options](/?path=/story/components-molecules-combobox--many-options) · frame: `/iframe.html?id=components-molecules-combobox--many-options&viewMode=story`
- [Grouped](/?path=/story/components-molecules-combobox--grouped) · frame: `/iframe.html?id=components-molecules-combobox--grouped&viewMode=story`
- [In context](/?path=/story/components-molecules-combobox--in-context) · frame: `/iframe.html?id=components-molecules-combobox--in-context&viewMode=story`
- [Keyboard flow](/?path=/story/components-molecules-combobox--keyboard-flow) — interaction test · frame: `/iframe.html?id=components-molecules-combobox--keyboard-flow&viewMode=story`
- [Active descendant (interaction test, known bug)](/?path=/story/components-molecules-combobox--active-descendant) — interaction test · frame: `/iframe.html?id=components-molecules-combobox--active-descendant&viewMode=story`

## Patterns consulted

- Patterns/Forms · ChoiceControls
- Patterns/Overlays · OverlayChoice
- Patterns/Decision Matrix · ComponentChoice

## Decisions that name it

- ADR-003 — Storybook editorial convention and pattern↔component bidirectionality
- ADR-005 — Visual operational rules: surfaces, interaction, motion
- ADR-006 — Geometry and typography signature
- ADR-024 — `LocaleSelector` is a new molecule, not an extension of `Combobox`

## Always

- Tokens only (R04); variants are semantic axes, never appearance (R02).
- Typography and actions are Poesía atoms, never raw HTML with utilities.
- Vibrant panes need a ground and never nest (ADR-027).
