Autocomplete

Typeahead input that filters suggestions as you search.

Installation

npx shadcn@latest add @iconiq/b-autocomplete

File Structure

Usage

"use client";

import { useState } from "react";

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

type Country = {
  code: string;
  name: string;
  region: string;
};

const countries: Country[] = [
  { code: "CA", name: "Canada", region: "North America" },
  { code: "FR", name: "France", region: "Europe" },
  { code: "JP", name: "Japan", region: "Asia" },
  { code: "MX", name: "Mexico", region: "North America" },
  { code: "US", name: "United States", region: "North America" },
];

export function AutocompletePreview() {
  const [query, setQuery] = useState("");

  return (
    <div className="w-full max-w-xl">
      <Autocomplete
        itemToStringValue={(country) => country.name}
        items={countries}
        onValueChange={setQuery}
        value={query}
      >
        <AutocompleteInput
          label="Search countries"
          placeholder="e.g. Canada"
        />
        <AutocompleteContent>
          <AutocompleteList>
            {(country: Country, index: number) => (
              <AutocompleteItem
                description={country.region}
                index={index}
                key={country.code}
                value={country}
              >
                {country.name}
              </AutocompleteItem>
            )}
          </AutocompleteList>
          <AutocompleteEmpty>No country matches that query.</AutocompleteEmpty>
        </AutocompleteContent>
      </Autocomplete>
    </div>
  );
}

Props

Props
Description

Autocomplete

items

Item collection used for list filtering. Pass a flat array or grouped items for sectioned results.

Type readonly Item[]

value

Controlled input text shown in the field.

Type string

defaultValue

Initial input text for uncontrolled usage.

Type string

onValueChange

Called when the input text changes from typing or when a suggestion is accepted.

Type (value: string, eventDetails) => void

itemToStringValue

Maps each item to the string used for filtering and the committed input value.

Type (item: Item) => string

autoHighlight

Automatically highlights the first matching item while typing.

Type boolean | "always"·Default true

keepHighlight

When true, keeps the highlighted item when the pointer leaves the list.

Type boolean·Default false

open

Controlled popup state. Pair with onOpenChange.

Type boolean

onOpenChange

Called when the suggestion panel opens or closes. Use with open for controlled popup state.

Type (open: boolean, eventDetails) => void

onItemHighlighted

Called when the highlighted suggestion changes from keyboard, pointer, or programmatic updates.

Type (item: Item | undefined, eventDetails) => void

openOnInputClick

When true, clicking the input opens the suggestion panel even before typing.

Type boolean·Default false

submitOnItemClick

When true, selecting an item submits the owning form. Useful for search inputs.

Type boolean·Default false

modal

When true, traps focus inside the popup. Pair with AutocompleteBackdrop for a dimmed overlay.

Type boolean·Default false

isItemEqualToValue

Custom equality for object items. Use when items are recreated on each render.

Type (item: Item, value: Item) => boolean

AutocompleteInput

label

Optional field label rendered above the input and linked with htmlFor.

Type React.ReactNode

labelClassName

Optional class names merged onto the field label.

Type string

placeholder

Shown when the input is empty.

Type string

showClear

Controls whether AutocompleteClear is rendered.

Type boolean·Default true

showTrigger

When true, renders a chevron trigger that toggles the suggestion panel.

Type boolean·Default false

disabled

Disables the input, clear button, and trigger.

Type boolean·Default false

aria-invalid

When true, applies destructive border and ring styling to the input shell.

Type boolean | 'true' | 'false'

AutocompleteClear

disabled

Disables the clear button.

Type boolean·Default false

className

Merged onto the clear button.

Type string

AutocompleteTrigger

disabled

Disables the trigger button.

Type boolean·Default false

AutocompleteContent

side

Preferred side for the popup.

Type "top" | "right" | "bottom" | "left"·Default "bottom"

align

Popup alignment relative to the input anchor.

Type "start" | "center" | "end"·Default "start"

sideOffset

Distance between the input and the popup.

Type number·Default 6

className

Merged onto the animated popup panel.

Type string

AutocompleteList

children

Render explicit AutocompleteItem children or a render function when using the root items prop.

Type ReactNode | ((item, index) => ReactNode)

className

Merged with the default list spacing and scroll classes.

Type string

AutocompleteItem

value

Item value passed to Base UI for selection handling.

Type Item

description

Optional secondary line below the primary label.

Type ReactNode

AutocompleteEmpty

children

Message shown when the filtered list is empty.

Type ReactNode·Default "No results found."

AutocompleteStatus

children

Status text announced politely to screen readers, such as Loading or No matches.

Type ReactNode

AutocompleteGroup

items

Items rendered inside this group when using grouped root items.

Type readonly Item[]

AutocompleteLabel

children

Group heading text.

Type ReactNode

AutocompleteSeparator

Horizontal divider between suggestion groups or rows.

AutocompleteCollection

Renders the current filtered collection when not using AutocompleteList render props.

AutocompleteValue

Reads the current input value from context for custom display layouts.

AutocompleteIcon

Leading icon slot rendered inside AutocompleteInput.

AutocompleteBackdrop

Dimmed overlay for modal autocomplete usage. Render as a sibling of AutocompleteContent when modal is true.

AutocompleteRow

Row wrapper for multi-column or complex suggestion layouts.

Registry bundle

Install the exact registry entry shown on the right when you want the component file and its declared runtime dependencies together.

Dependencies: @base-ui/react, motion, lucide-react.

This page documents the Base UI install only. Radix UI does not ship a dedicated autocomplete primitive.

Install into components/ui/b-autocomplete.tsx so imports match the usage examples.

The generated registry file is /r/b-autocomplete.json.

Contact

Additionally, if you find any bug or issue, feel free to raise an issue.

Type to filter suggestions