Combobox

Pro

Searchable select that opens a list of options and highlights the letters you type in each one. It forgives typos and initials, shows recent picks before you type, and can add a new option.

Preview

Installation

npx @lumioui/cli add pro/combobox

Usage

import { Combobox } from "@/components/ui/combobox/combobox";
<Combobox />

API reference

Prop Type Default
options* ComboboxOption[] —
value string

Controlled value. Pair with onValueChange; omit for uncontrolled.

 —
defaultValue string

Uncontrolled initial value. Ignored when value is provided.

 —
onValueChange (value: string) => void

Selection callback — optional so uncontrolled usage needs no wiring.

 —
open boolean

Controlled open state. Pair with onOpenChange; omit for uncontrolled.

 —
onOpenChange (open: boolean) => void —
disabled boolean

Disables the trigger — dims it and blocks opening the sheet.

 false
placeholder string "Select…"
searchPlaceholder string "Search…"
title string

Optional sheet heading. Rendered only when provided.

 —
recent string[]

Values shown under "Recent" before anything is typed. Picks made in the sheet join the front of this list.

 —
suggested string[]

Values shown under "Suggested" before anything is typed.

 —
sectionLabels { recent?: string

Section headings. Defaults "Recent", "Suggested", "All".

 —
suggested string —
all string } —
onQueryChange (query: string) => void

Fires as the search text changes — fetch remote options here.

 —
loading boolean

Results are on their way: rows on screen hold still and dim; with no rows yet, dim placeholder rows hold the layout.

 false
filter boolean

Fuzzy-filter and rank options locally. Default true; turn off when the server already filtered — matches are still lit.

 true
onCreate
(query: string) => ComboboxOption … (query: string) => ComboboxOption | void | Promise<ComboboxOption | void>

Offer an "Add “…”" row when no option's label equals the query. Return the new option (or a promise of it) to pick it straight away.

 —
createLabel (query: string) => string

Create row label. Default Add “query”.

 (q) => `Add “${q}”`
createHint string

Second line of the create row, e.g. "New traveller".

 —
emptyText string

Line under "No match for …".

 "Check the spelling
emptyAction ComboboxEmptyAction

The empty state's action. Default clears the search.

 —
className string —