Skip to content
quartiledocsv0.1
GitHub

Select

Preview

A listbox select with grouped options, descriptions and disabled states.

Example

const metricOptions = [
  { value: 'net', label: 'Net revenue', description: 'sum · USD', group: 'Revenue' },
  { value: 'gross', label: 'Gross revenue', description: 'sum · USD', group: 'Revenue' },
  { value: 'aov', label: 'Avg. order value', description: 'mean · USD', group: 'Revenue' },
  { value: 'orders', label: 'Orders', description: 'count', group: 'Volume' },
  { value: 'ltv', label: 'Lifetime value', description: 'needs plan', group: 'Volume', disabled: true },
];

<Select label="Metric" options={metricOptions} value={metric} onChange={setMetric} />

Usage

Options with the same group are listed under one heading. description is a right-aligned mono note, which can say why an option is disabled. Set name to submit the value with a form. The list renders in the provider's portal layer; set portal={false} to keep it in place. For long lists, use Combobox.

Props

Select

PropTypeDefaultDescription
optionsrequiredSelectOption[]——
valuestring | null——
defaultValuestring | nullnull—
onChange(value: string, option: SelectOption) => void——
placeholderstring'Select…'—
labelReactNode——
hintReactNode——
errorReactNode——
size'sm' | 'md' | 'lg'InputSize'md'—
disabledboolean——
namestring—Submits the value with a form under this name.
idstring——
openboolean——
defaultOpenbooleanfalse—
onOpenChange(open: boolean) => void——
portalbooleantrueRender the list in the provider's portal layer (default) or in place, below the trigger. In place suits lists that should stay inside a scrolling container.
classNamestring——
styleCSSProperties——
aria-labelstring——

SelectOption

PropTypeDefaultDescription
valuerequiredstring——
labelrequiredstring——
descriptionReactNode—Right-aligned mono note, e.g. "sum · USD" or why the option is disabled ("needs plan").
disabledboolean——
groupstring—Options with the same group are listed under one heading, in the order they first appear.

Accessibility

  • A button that opens a listbox, labelled by label or aria-label.
  • ↑ ↓ Home End move, Enter or Space picks, Escape closes, and typing jumps to a matching option.
Report an issueBuilt Oct 21, 2026