Picker

Playground

Installation

pnpm add @tessinaui/ui

Usage

import { Picker, PickerSkeleton } from "@tessinaui/ui";

{/* Basic — the trailing chevron is the default glyph */}
<Picker
  label="Style"
  options={[
    { value: "vega", label: "Vega" },
    { value: "nova", label: "Nova" },
    { value: "maia", label: "Maia" },
  ]}
  defaultValue="nova"
/>

{/* Controlled, with per-option adornments (the trigger falls back to the
    selected option's adornment when no trigger adornment is given) */}
<Picker
  label="Base Color"
  options={[
    { value: "violet", label: "Violet", adornment: <span className="size-3.5 rounded-full" style={{ background: "var(--chart-1)" }} /> },
    { value: "blue",   label: "Blue",   adornment: <span className="size-3.5 rounded-full" style={{ background: "var(--chart-2)" }} /> },
  ]}
  value={color}
  onValueChange={setColor}
/>

{/* Loading */}
<PickerSkeleton />

Stack pickers full-width in a sidebar on desktop, or give each a fixed width (e.g. w-36 shrink-0) inside a horizontally scrolling strip on mobile — setting rows stack flush (the row height is the rhythm).

When not to use a Picker

• Searching or filtering a long list → Combobox. A Picker's list is known and short; past ~15 options you want typing.
• A form field with helper/error text, label layouts or multi-select → Select. Picker's intent tints the boundary only, on purpose.
• Commands and actions → DropdownMenu. Options describe state; menus do things (HIG's pop-up vs pull-down split).
• Time/date wheels → TimePicker / native inputs.

Selection applies instantly and the popup closes on choose — a Picker is never behind an Apply button. Give it a sensible defaultValue: the placeholder is a hint, never the label. Provide option adornments for all options in a group or none of them, and order short lists semantically (most-used first) rather than alphabetically.

Examples

Default

Variants

Sizes

Rounded

Adornments

Option descriptions & badges

Grouped options

States & intents

On color

Loading & empty

Controlled

Self-previewing values

Popup footer

Mobile strip

Paired pickers

In a form

Accessibility

• The trigger is a role="combobox" button named by the visible caption + value (aria-labelledby) — it announces as e.g. "Style Nova". Never add a duplicate aria-label.
• The option list is a real role="listbox"; the popup shell around it is presentational, which is what makes popupFooter content legal.
• emptyText/loadingText render as disabled option rows (a listbox must never own zero options); the list is aria-busy while loading.
• Option description reaches AT via aria-describedby — the option's name stays its label. Rich label nodes need textValue for typeahead and announcements.
• required renders a star plus screen-reader text and aria-required; intent="error" stamps aria-invalid and data-invalid.
• Full keyboard: Space/Enter/ArrowUp/ArrowDown open; arrows + Home/End move; Space/Enter select; Esc closes back to the trigger; typeahead works on the closed trigger and the open list.
• AT matrix: VoiceOver (macOS) verified locally; NVDA and JAWS are UNTESTED on this project's hardware.

API Reference

Picker props

The trigger also accepts every native button attribute (id, data-*, aria-*, event handlers) — it is the control, so everything lands on it.

PickerOption

PickerSkeleton props

Data attributes

data-component="picker" and data-slot on every part (picker-trigger/label/value/adornment/popup/list/item/item-description/item-trailing/item-indicator/group/group-label/separator/footer/loading/empty/skeleton), plus state marks: data-empty, data-invalid, data-variant, data-tone, and the primitive's data-popup-open/data-disabled/data-selected/data-highlighted.