Select

When to use

• One value from a fixed list that is too long for radios: a country, a time zone, a sort order, a role.
• Options the user already recognises. Picking beats typing when the choices are known and short enough to scan.
• Limited space. The trigger shows only the current value, so the list costs no room until it is opened. Use variant="ghost" for a quiet toolbar or inline trigger.
• Several values from the same list with multiple: the popup stays open while the user toggles rows and the trigger summarises the count.
• A label that stays visible. Set label (or visuallyHiddenLabel where the row is hidden): the placeholder is a hint, never the name of the field.

When not to use

• For two to four choices that should stay visible. Use SegmentedControl or Radio; hiding a short list behind a click costs a step for nothing.
• For long or searchable lists. Typeahead only jumps to a match. When people need to filter, or type a value that is not listed, use Combobox.
• For actions. A select records a value, it does not do something. Use DropdownMenu for commands.
• For several independent on/off choices. Use Checkbox rather than multiple, so every option stays on screen.
• For options that need long explanations. Keep each option to one line; description is a second line, not a paragraph. Put longer guidance in supportingText or the page.

Installation

pnpm add @tessinaui/ui

Usage

import {
  SelectRoot,
  SelectTrigger,
  SelectPopup,
  SelectList,
  SelectItem,
} from "@tessinaui/ui";

<SelectRoot label="Fruit" value={value} onValueChange={setValue}>
  <SelectTrigger placeholder="Select a fruit…" />
  <SelectPopup>
    <SelectList>
      <SelectItem value="apple">Apple</SelectItem>
      <SelectItem value="banana">Banana</SelectItem>
      <SelectItem value="cherry">Cherry</SelectItem>
    </SelectList>
  </SelectPopup>
</SelectRoot>

When to use — and when not to

• Select — choose one value (or a few, with multiple) from a known, fixed list. Typeahead is built in; there is no text filtering.
• Past ~15 options, or any list a user would search rather than scan, reach for Combobox — it owns the filter input. Don't bolt a search field into a Select popup.
• Rows that act (delete, invite, navigate) belong in DropdownMenu — a listbox may only contain options; an action in an option list is a contract violation. One action under the list goes in a footer (see Footer action).
• A compact unit/currency selector attached to an input is FieldDropdown.
• A "guests / travellers" trigger that opens counter rows is a Popover + NumberField composition, not a Select.
• Time-period triggers that expand into calendars are DatePicker territory.
• Two or three visible choices → RadioGroup or SegmentedControl.
• A clearable single select is an explicit null item: <SelectItem value={null}>None</SelectItem>.

Examples

Default

A labelled select with a placeholder and a default selected value. The visible label is the accessible name (htmlFor association — clicking it focuses the trigger), and supportingText is announced via aria-describedby.

Sizes

Five trigger heights and text scales — xs, sm, md, lg, and xl. The shell text reads Field's own ladder, so a Select next to a Field always matches, 16px phone floor included.

Ghost variant

variant="ghost" drops the well for toolbars, table footers and inline config rows. A ghost trigger still needs a name — use visuallyHiddenLabel when the label would be visual noise.

Underline variant

variant="underline" draws the Field family's bottom-rule shell for dense forms: square whatever rounded says, no fill in any state, and focus — or an open popup — shown as an inset 2px bottom band in the intent colour instead of the ring.

Intents

Border and focus-ring colours for none, error, warning, success, and info. Warning helper text uses the tinted token — raw amber never renders as text.

Validation

errorMessage REPLACES supportingText (no layout shift), implies intent="error" unless a non-none intent is explicit, sets aria-invalid, and the swap is announced politely.

Multiple

multiple keeps the popup open while toggling, renders checkbox rows, and summarises the trigger: one selection shows its label (via the Root items map), more show "N selected". renderValue on the trigger is the formatting/i18n escape hatch.

On-color

On a coloured Surface the trigger adopts the shared well recipe — tone resolves from context, no prop needed. The popup stays a standard panel: a portal floats above the plate, it is not on it.

Leading Icon

Add an icon at the start of the trigger via the leadingIcon prop.

Item Descriptions

Two-line options via the description prop. The description stays out of the option's accessible name (it's wired as the option's description), so "Apple" announces as Apple, never "Apple Crisp and sweet".

Trailing meta

trailingText renders muted meta at the row's end — a phone code, a shortcut hint, a balance — outside the accessible name.

Status dots

Colour-coded options compose today: any node in leadingIcon.

Grouped Options

Base UI group primitives: each group is named by its label for screen readers.

Scrollable

The List caps to the viewport (--available-height) and scrolls; hover the arrows on desktop. On touch the arrows never render — native scrolling is the path.

States

disabled, readOnly (focusable and announced, but not operable), and disabled options.

Custom value rendering

renderValue plus the Root items map: echo the selected item's icon in the trigger, format joined labels, localise the multi summary.

Footer action

A "Create…" row below the options. It's legal because the List carries role="listbox" and the Popup demotes to role="presentation" — the button sits outside the listbox. It is Tab-reachable, not part of the arrow-key option navigation.

RTL

dir="rtl" mirrors the trigger (value on the right, chevron on the left) and is restated on the portalled positioner, so the popup lines up with the trigger's right edge. Up and down arrow keys work the same. Leave dir unset and the select inherits the page's direction.

API Reference

SelectRoot props

Reference-only passthrough (Base UI Root): open / defaultOpen / onOpenChange, onOpenChangeComplete, modal, actionsRef, itemToStringLabel / itemToStringValue / isItemEqualToValue, autoComplete, inputRef, form.

SelectTrigger props

SelectItem props

SelectPopup props

SelectSkeleton props

All other sub-components (SelectGroup, SelectGroupLabel, SelectSeparator, SelectScrollUpArrow, SelectScrollDownArrow, SelectSupportingText, SelectList) forward their Base UI part's props plus className.

Accessibility

Implements the WAI-ARIA select-only combobox pattern via Base UI: the trigger is role="combobox" with aria-controls pointing at the role="listbox" List (aria-multiselectable with multiple).

• The visible label is the accessible name (htmlFor — click focuses). visuallyHiddenLabel keeps the name when the row is hidden. There is no aria-label duplication.
• supportingText / errorMessage / infoText are joined into aria-describedby; the meta row is aria-live="polite", and the error replaces the helper so validation never shifts layout.
• Options announce as their label alone — description is the option's accessible description, trailingText stays out of both.
• Groups are named by SelectGroupLabel.
• Touch targets: 44px trigger + item floors on touch — a coarse pointer at any width, or a viewport under 768px; forced-colors maps highlight/selection to Highlight/HighlightText; popup motion and the chevron rotation respect prefers-reduced-motion.

Keyboard

AT matrix

Known limitations

• iOS VoiceOver + Safari: the portalled listbox relies on aria-owns semantics Safari doesn't implement; an inline-popup mode — the list rendered in place rather than portalled — is tracked in the backlog.
• The scroll arrows are a desktop-hover affordance and never render on touch — native scrolling covers it; don't make them the only overflow cue.

Migrating