Autocomplete

Search field with live suggestions that highlight the letters you’ve typed. Shows recent searches while empty and a loading state, and picking a row lifts it straight into the field.

Preview

Installation

npx @lumioui/cli add autocomplete

Usage

import { filterOptions, Autocomplete } from "@/components/ui/autocomplete/autocomplete";
<Autocomplete />

Also exported: filterOptions.

Examples

Address lookup

The delivery address step in a food app.

Station search

The To field of a rail ticket.

Payment recipient

"Send to" in a money app.

API reference

Prop Type Default
value string

Controlled query text.

—
defaultValue string

Uncontrolled initial query.

""
onValueChange (query: string) => void

Fires on every keystroke (debounce in your fetcher if remote).

—
options AutocompleteOption[]

Candidate options. Filtered by the built-in ranking unless filter is false (then pass already-filtered results).

[]
filter
((options: AutocompleteOption[] … ((options: AutocompleteOption[], query: string) => AutocompleteOption[]) | false

Custom filter, or false to show options as-is (remote search).

—
recent AutocompleteOption[]

Shown while the query is empty.

—
recentTitle string

Header above recents. Default "Recent".

"Recent"
onClearRecent () => void

Shows a "Clear" action on the recent header.

—
resultsTitle string

Header above matches. Omit for none.

—
onSelect (option: AutocompleteOption) => void

Fires when a suggestion is picked.

—
fillOnSelect boolean

Fill the field with the picked title. Default true.

true
loading boolean

Skeleton rows while results load.

—
maxResults number

Max rows shown. Default 6.

6
minChars number

Characters before matching starts. Default 1.

1
highlightMatch boolean

Bold the typed part of each title. Default true.

true
emptyText string | ((query: string) => string)

Empty-results copy. Default No results for "<query>".

—
presentation "inline" | "dropdown"

"inline" (default) list under the field, always visible; "dropdown" floating card shown while the field is focused.

"inline"
open boolean

Controlled suggestion visibility.

—
onOpenChange (open: boolean) => void

Fires when suggestions open/close (focus, pick, blur).

—
placeholder string

Field placeholder. Default "Search".

"Search"
label string

Label above the field.

—
inputProps
Omit<SearchInputProps, "value" … Omit<SearchInputProps, "value" | "onChangeText" | "placeholder" | "label">

Extra props for the SearchInput field.

—
emptyQueryContent React.ReactNode

Content shown under recents while the query is empty (shortcuts).

—
className string —