Autocomplete

Overview

Use autocomplete when users type into an input and need suggestions from a list.

Autocomplete is useful for search, people pickers, command-style inputs, tags, addresses, and large option sets. It keeps typing as the main action while making valid choices easier to find.

Anatomy

Autocomplete includes an input, popup, list, items, and optional clear or trigger controls. The input owns the typed value. The popup shows matching suggestions. Each item should have clear display text and a stable value.

Behavior

Use local filtering for small lists. Use async search for remote data. Add a limit when the full list is large. Auto-highlight can speed up keyboard selection, but it should not surprise users by choosing an item before they confirm.

Accessibility

Provide a label through Field or another visible label. Keep keyboard navigation intact, including arrow keys, Enter, Escape, and focus return. Make empty and loading states clear when suggestions come from a server.

Installation

npx love-ui@latest add autocomplete

Usage

import {
  Autocomplete,
  AutocompleteEmpty,
  AutocompleteInput,
  AutocompleteItem,
  AutocompleteList,
  AutocompletePopup,
} from "@/components/ui/autocomplete"

const items = [
  { value: "apple", label: "Apple" },
  { value: "banana", label: "Banana" },
  { value: "orange", label: "Orange" },
  { value: "grape", label: "Grape" },
]

<Autocomplete items={items}>
  <AutocompleteInput placeholder="Search..." />
  <AutocompletePopup>
    <AutocompleteEmpty>No results found.</AutocompleteEmpty>
    <AutocompleteList>
      {(item) => <AutocompleteItem key={item.value} value={item}>{item.label}</AutocompleteItem>}
    </AutocompleteList>
  </AutocompletePopup>
</Autocomplete>

API Reference

The AutocompleteInput component extends the original Base UI component with a few extra props:

Examples

These examples show disabled, sized, labeled, grouped, limited, async, and form-connected autocomplete patterns.

Disabled

Use disabled when the user cannot search or choose yet.

Small Size

Use the small size in compact toolbars, filters, or dense forms.

Large Size

Use the large size when the input is a primary search or selection control.

With Label

Use a label whenever the autocomplete appears in a form or settings area.

Inline Autocomplete

Autofill the input with the highlighted item while navigating with arrow keys.

Auto Highlight

Automatically highlight the first matching option.

With Clear Button

Use a clear button when users often need to reset the value.

With Trigger and Clear Buttons

Use a trigger button when users may want to browse options without typing.

With Groups

Use groups when suggestions have meaningful categories.

With Limit Results

Limit results to keep the popup quick to scan.

Async Search

Use async search when suggestions come from an API or remote index.

Form Integration

Use form integration when the selected value must be validated and submitted.