Autocomplete

A text input that suggests options as the user types. Queries are debounced through the delay prop so a burst of keystrokes makes a single request, and passing onQueryChange switches the component into async mode where the caller owns filtering and the supplied items render verbatim. Supports a dropdown trigger, multi-select chips, grouped and object suggestions, forced selection, loading status, and a minimum query length.

Installation

Import from the package. Do not run shadcn add in your app.

tsx

import { Autocomplete } from "@carsxe/design-system/components/autocomplete"

Usage

tsx

import {
  Autocomplete,
  AutocompleteContent,
  AutocompleteEmpty,
  AutocompleteInput,
  AutocompleteItem,
  AutocompleteList,
} from "@carsxe/design-system/components/autocomplete"

<Autocomplete items={makes} delay={300} onQueryChange={search}>
  <AutocompleteInput placeholder="Search vehicle make" />
  <AutocompleteContent>
    <AutocompleteEmpty>No makes found.</AutocompleteEmpty>
    <AutocompleteList>
      {(make) => (
        <AutocompleteItem key={make} value={make}>
          {make}
        </AutocompleteItem>
      )}
    </AutocompleteList>
  </AutocompleteContent>
</Autocomplete>

Debounced async suggestions

Queries fire 400ms after you stop typing, so a burst of keystrokes makes a single request.

Dropdown trigger and clear button

Multiple selection with chips

Ford

Grouped object suggestions

Force selection

Type something that is not a make, then click away — the input resets.

API Reference

Prop	Type	Default
items	T[] \| { value, items }[]	—
delay	number	250 (ms)
onQueryChange	(query: string) => void	—
minLength	number	1
loading	boolean	false
filter	null \| (item, query) => boolean	—
limit	number	—
itemToStringValue	(item: T) => string	—
multiple	boolean	false
forceSelection	boolean	false
value	string \| T[]	—
defaultValue	string \| T[]	—
onValueChange	(value: string \| T[]) => void	—
onSelect	(item: T) => void	—
onUnselect	(item: T) => void	—
onClear	() => void	—
open	boolean	—
onOpenChange	(open: boolean) => void	—
autoHighlight	boolean \| "always"	false
openOnInputClick	boolean	false
disabled	boolean	false
readOnly	boolean	—
required	boolean	—
invalid	boolean	false
name	string	—