Shadcn Autocomplete Components

Shadcn Autocomplete Component

The Shadcn Autocomplete is a text input that suggests matching options while the user types. It speeds up search boxes, tag fields and people pickers, because users can accept a suggestion with one key press instead of typing the whole value, but they are never forced to pick something from the list.

Need suggestions while the user types instead of a fixed list of choices? This React autocomplete component comes in five variants: a basic search field, one with a clear button, grouped suggestions with labels, async results loaded from an API and automatic highlighting of the first match. It is built with shadcn/ui, React and Tailwind CSS on top of the Autocomplete primitive from Base UI, which handles filtering, keyboard navigation and popup positioning.

What is the Shadcn Autocomplete Component?

An autocomplete pairs a text field with a floating list of suggestions. The value is the text in the input: selecting a suggestion simply fills the field, and whatever the user typed stays valid even when nothing in the list matches. Base UI implements the WAI-ARIA combobox pattern for it, so focus stays in the input while the highlighted suggestion moves through the list.

Choose between similar inputs by the value you store. Use an autocomplete for free text with hints, such as search terms, tags or addresses. Use a Combobox when the value must be one of the listed options, a Select for short lists where typing is not needed, and a Command menu for a full command palette with actions and shortcuts.

Anatomy of the Shadcn Autocomplete

5 Shadcn Autocomplete Variants

Each autocomplete variant listed here is previewed live at the top of this page, together with its source code and install command.

• Basic: A search field with a filtered list of labels and component names, plus an empty message when nothing matches.
• With clear button: A controlled input with showClear, so users can reset the text with one click.
• With groups and labels: People grouped by team with sticky group labels, avatars and job titles, filtered across name, team and position.
• Async items loading: Debounced remote search of a developer directory with a spinner, a result count and an error message rendered in AutocompleteStatus. The input shows both the clear and the trigger button.
• Auto highlight: Uses autoHighlight to highlight the first match, so pressing Enter accepts it right away.

How to Install the Shadcn Autocomplete Component

Set up shadcn/ui in your project if you have not already, then add the Shadcn UI Kit registry to your components.json once:

{
  "registries": {
    "@shadcnuikit": "https://shadcnuikit.com/r/{name}.json"
  }
}

Then install a autocomplete variant by its name:

npx shadcn@latest add @shadcnuikit/autocomplete1

The same command works with pnpm dlx, yarn dlx and bunx --bun. Each variant has a copy button for every package manager, and the code is added to your project as plain React and Tailwind CSS that you can edit freely.

How to Use the Shadcn Autocomplete Component

Pass your data to items on the root and render each suggestion with the function child of AutocompleteList. The built-in filter matches the input text against each item value.

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

const tags = ["feature", "fix", "bug", "docs", "design"]

export function TagSearch() {
  return (
    <Autocomplete items={tags}>
      <AutocompleteInput placeholder="Search tags" showClear />
      <AutocompleteContent>
        <AutocompleteEmpty>No tags found.</AutocompleteEmpty>
        <AutocompleteList>
          {(tag: string) => (
            <AutocompleteItem key={tag} value={tag}>
              {tag}
            </AutocompleteItem>
          )}
        </AutocompleteList>
      </AutocompleteContent>
    </Autocomplete>
  )
}

Why Use the Shadcn Autocomplete Component

• Faster input: Users type a few letters and accept a suggestion, which cuts typing and spelling mistakes.
• Free text stays valid: Unlike a select or combobox, the value does not have to match the list, so custom search terms still work.
• Accessible by default: Base UI provides the ARIA roles, the highlighted option tracking and the keyboard handling.
• Handles large and remote data: Pass pre-filtered results and set filter to null to show server results as they are.
• Fully styleable: Every part accepts a className and uses theme tokens such as bg-popover, so dark mode works automatically.

Common Autocomplete Use Cases

• Site and product search: Suggest popular queries or product names while users type in a search bar.
• User and team pickers: Find people by name, role or department when inviting or assigning them.
• Tag inputs: Suggest existing labels but still let users create a new one.
• Address and city fields: Complete locations from an API as the user types a few characters.
• Filter bars: Narrow tables and dashboards with suggested values for a column.
• Mentions and recipients: Suggest contacts in message composers and email recipient fields.

Customizing the Shadcn Autocomplete

Items can render anything, from a single line of text to an Avatar with a name and job title. Change the popup placement with side, align and sideOffset on AutocompleteContent, and style the highlighted row with the data-highlighted attribute. Colors come from your theme variables, so a palette from the free Theme Generator applies automatically.

For remote data, filter on the server and turn off the built-in filter:

<Autocomplete
  items={results}
  value={query}
  onValueChange={setQuery}
  filter={null}
>
  <AutocompleteInput placeholder="Search developers" showClear />
  <AutocompleteContent>
    <AutocompleteStatus>
      {loading ? "Searching..." : `${results.length} results`}
    </AutocompleteStatus>
    <AutocompleteList>{/* items */}</AutocompleteList>
  </AutocompleteContent>
</Autocomplete>

Autocomplete Accessibility and Keyboard Support

Base UI follows the WAI-ARIA combobox pattern: the input announces that a list of suggestions is available, the highlighted option is tracked with aria-activedescendant and focus never leaves the text field. Give the input a visible label or an aria-label, and keep empty and status messages short so screen readers can announce them quickly.

Autocomplete Best Practices

• Start suggesting after one or two characters, and debounce remote requests by around 300 ms.
• Set filter to null when the server already filters the results, so they are not filtered twice.
• Always show a clear message for no results, loading and errors instead of an empty popup.
• Keep the list short and relevant; group long lists by category with group labels.
• Use autoHighlight when the first match is almost always the right one.
• If the value must match a record, use a Combobox instead.

Components Related to Autocomplete

Shadcn Autocomplete FAQ

Looking for something else? Browse all shadcn/ui components or ready-made UI blocks built with them.