# Selects and comboboxes

Choose the simplest selection control that lets people find and compare the available options.

## Decision rule

| Variant | Use when | Opening behavior |
| --- | --- | --- |
| Standard select | Roughly 2–8 stable, easily scanned options | Show options immediately; no search field |
| Searchable select / combobox | People, owners, assets, countries, dynamic collections, or generally more than 8–10 options | Focus the search input and filter the list |

The numeric threshold is guidance, not a substitute for judgment. Eight unfamiliar organization names may benefit from search, while twelve familiar months do not.

## Shared anatomy

- A persistent visible label.
- A 40px trigger using `--control-height` and `--radius-control`.
- The selected value and a disclosure icon.
- A popup at least as wide as the trigger, with a practical maximum height around 256px.
- A selected row identified by both background treatment and a checkmark.
- Optional secondary metadata when it helps distinguish similar entities.
- An explicit empty state when filtering returns no results.

The popup should flip above the trigger when there is insufficient space below and remain within the viewport.

## Standard select

Prefer the native `select` when its platform behavior and styling are sufficient. If a custom listbox is required, it must provide the same keyboard and form semantics. Do not add a search field to a short list merely for visual consistency with searchable controls.

## Searchable select

- Move focus to the search input whenever the popup is opened.
- Filter by the primary label and useful secondary identifiers.
- Clear the search query when the popup closes unless preserving it supports an explicit multi-select workflow.
- Do not fetch on every keystroke without debouncing and an announced loading state.
- Keep the last valid selection if a remote search fails.

## Keyboard contract

- `ArrowDown` or `ArrowUp` opens the popup from the trigger.
- Arrow keys move through visible options.
- `Home` and `End` move to the first and last visible option.
- `Enter` selects the focused option.
- `Escape` closes without changing the selection and returns focus to the trigger.
- `Tab` accepts the normal focus order; it must not trap focus in the popup.

Use the combobox and listbox ARIA patterns consistently. Keep `aria-expanded`, `aria-controls`, `aria-selected`, and the accessible label synchronized with visible state.

## Content

Use entity names as primary text. Secondary text may contain an email, identifier, or organization. Avoid status badges and long descriptions inside a selection row unless they are essential to choosing correctly.