Skip to content
quartiledocsv0.1
GitHub

Combobox

Preview

A filterable select for long option lists, single or multiple, with an optional figure beside each option.

Example

North AmericaEurope
Price on the right
// meta: each region's revenue, e.g. "$179K"
const regionOptions = REGIONS.map((region) => {
  const revenue = orders.filter((o) => o.region === region).reduce((s, o) => s + o.amount, 0);
  return { value: region, label: region, meta: `$${Math.round(revenue / 1000)}K` };
});
const productOptions = PRODUCTS.map((p) => ({ value: p.sku, label: p.name, meta: `$${p.price}` }));

<Combobox
  multiple
  label="Regions"
  options={regionOptions}
  value={regions}
  onChange={setRegions}
  placeholder="Filter regions…"
/>

<Combobox
  label="Product"
  options={productOptions}
  defaultValue="KST-1042"
  placeholder="Search products…"
  hint="Price on the right"
/>

Usage

Without multiple, value is a string (or null) and the input shows the chosen label. With it, value is an array and choices show as removable chips. The default filter is a case-insensitive substring match on the label; pass filter to change it. meta is a right-aligned mono figure, such as the revenue behind each option.

Props

A union of ComboboxSingleProps and ComboboxMultipleProps: the types of value and onChange follow multiple.

PropTypeDefaultDescription
multipletrue | false—Pick several options; they show as removable chips.
valuestring[] | string | null——
defaultValuestring[] | string | null——
onChange(value: string[]) => void | (value: string | null) => void——
optionsrequiredComboboxOption[]——
placeholderstring——
labelReactNode——
hintReactNode——
errorReactNode——
size'sm' | 'md' | 'lg'InputSize'md'—
disabledboolean——
emptyTextReactNode'No matches'Shown when nothing matches the query.
filter(option: ComboboxOption, query: string) => booleandefaultFilterCustom filter; defaults to a case-insensitive substring match on the label.
showFooterbooleantrueKeyboard hints and the match count under the list.
portalbooleantrueRender the list in place instead of the portal layer.
idstring——
classNamestring——
styleCSSProperties——
aria-labelstring——

ComboboxOption

PropTypeDefaultDescription
valuerequiredstring——
labelrequiredstring——
metaReactNode—Right-aligned mono figure, e.g. the revenue behind the option ("$224K").
disabledboolean——

Accessibility

  • A combobox input controlling a listbox: ↑ ↓ move the highlight, Enter picks (toggles, with multiple), Escape closes.
  • Each chip's remove button is keyboard-reachable, and Backspace on an empty query removes the last chip.
  • The footer shows the match count and keyboard hints; hide it with showFooter.
Report an issueBuilt Oct 21, 2026