Autocomplete

Installation

pnpm dlx shadcn@latest add https://prototyper-ui.com/r/autocomplete.json

npx shadcn@latest add https://prototyper-ui.com/r/autocomplete.json

yarn dlx shadcn@latest add https://prototyper-ui.com/r/autocomplete.json

bunx --bun shadcn@latest add https://prototyper-ui.com/r/autocomplete.json

This will add the following files to your project:

components/ui/autocomplete.tsx

Usage

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

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

Anatomy

<Autocomplete>
  <AutocompleteInput />
  <AutocompleteContent>
    <AutocompleteEmpty />
    <AutocompleteGroup>
      <AutocompleteGroupLabel />
      <AutocompleteList>
        <AutocompleteItem />
      </AutocompleteList>
    </AutocompleteGroup>
  </AutocompleteContent>
</Autocomplete>

Sub-component	`data-slot`	Purpose	Required
`Autocomplete`	-	Root provider, manages state and filtering	Yes
`AutocompleteInput`	`input-group-control`	Text input with optional trigger button	Yes
`AutocompleteTrigger`	`autocomplete-trigger`	Button that toggles the popup open/closed	No
`AutocompleteValue`	`autocomplete-value`	Displays the current value	No
`AutocompleteContent`	`autocomplete-content`	Positioned popup containing the list	Yes
`AutocompleteList`	`autocomplete-list`	Scrollable list of items	Yes
`AutocompleteItem`	`autocomplete-item`	Individual suggestion option	Yes
`AutocompleteEmpty`	`autocomplete-empty`	Shown when no items match the filter	No
`AutocompleteGroup`	`autocomplete-group`	Groups related items together	No
`AutocompleteGroupLabel`	`autocomplete-group-label`	Label for a group of items	No
`AutocompleteSeparator`	`autocomplete-separator`	Visual separator between groups	No
`AutocompleteIcon`	`autocomplete-icon`	Icon element	No
`AutocompleteStatus`	`autocomplete-status`	Screen-reader-only status message	No
`AutocompleteArrow`	`autocomplete-arrow`	Arrow pointing from popup to trigger	No
`AutocompleteBackdrop`	`autocomplete-backdrop`	Full-screen backdrop behind the popup	No

Autocomplete vs Combobox

Feature	Autocomplete	Combobox
Free-form text input	Yes	No (must select an item)
Selection tracking	No	Yes (`value`/`onValueChange`)
Multi-select / chips	No	Yes
Item check indicator	No	Yes
Trigger button	Optional (`showTrigger`)	Default
`mode` prop	Yes (`list`, `both`, `inline`, `none`)	No

Examples

Modes

Sections

Disabled

With Trigger

Styling

Data Slots

Use data-slot attributes to target specific parts of the autocomplete:

Slot name	Element
`input-group-control`	The text input element
`autocomplete-trigger`	Dropdown trigger button
`autocomplete-content`	Positioned popup panel
`autocomplete-list`	Scrollable list container
`autocomplete-item`	Individual suggestion
`autocomplete-empty`	Empty state message
`autocomplete-group`	Group container
`autocomplete-group-label`	Group label
`autocomplete-separator`	Separator line between groups
`autocomplete-value`	Value display
`autocomplete-icon`	Icon element
`autocomplete-status`	Screen-reader status (visually hidden)
`autocomplete-arrow`	Popup arrow
`autocomplete-backdrop`	Full-screen backdrop

Customization Examples

/* Widen the popup */
[data-slot="autocomplete-content"] {
  @apply min-w-[20rem];
}

/* Custom highlighted item style */
[data-slot="autocomplete-item"][data-highlighted] {
  @apply bg-primary text-primary-foreground;
}

{/* Override popup alignment */}
<AutocompleteContent align="center" sideOffset={8}>
  {/* ... */}
</AutocompleteContent>

API Reference

Root component that manages filtering, suggestions, and open/close state.

Prop

Type

All Base UI Autocomplete.Root props are forwarded via ...props.

AutocompleteInput

Text input with optional trigger button, wrapped in an InputGroup.

Prop

Type

All Base UI Autocomplete.Input props are forwarded via ...props.

AutocompleteTrigger

Button that toggles the popup open or closed. Renders a chevron-down icon by default.

Prop

Type

All Base UI Autocomplete.Trigger props are forwarded via ...props.

AutocompleteValue

Displays the current input value.

All Base UI Autocomplete.Value props are forwarded via ...props.

AutocompleteContent

Positioned popup that contains the list. Wraps Autocomplete.Portal, Autocomplete.Positioner, and Autocomplete.Popup.

Prop

Type

All Base UI Autocomplete.Popup props are forwarded via ...props.

AutocompleteList

Scrollable list container for autocomplete items.

Prop

Type

All Base UI Autocomplete.List props are forwarded via ...props.

AutocompleteItem

Individual suggestion option. Unlike ComboboxItem, does not include a check-mark indicator.

Prop

Type

All Base UI Autocomplete.Item props are forwarded via ...props.

AutocompleteEmpty

Message shown when no items match the current filter.

Prop

Type

All Base UI Autocomplete.Empty props are forwarded via ...props.

AutocompleteGroup

Groups related autocomplete items together.

Prop

Type

All Base UI Autocomplete.Group props are forwarded via ...props.

AutocompleteGroupLabel

Label for a group of items.

Prop

Type

All Base UI Autocomplete.GroupLabel props are forwarded via ...props.

AutocompleteSeparator

Visual separator between groups.

Prop

Type

All Base UI Autocomplete.Separator props are forwarded via ...props.

AutocompleteIcon

Icon element within the autocomplete.

Prop

Type

All Base UI Autocomplete.Icon props are forwarded via ...props.

AutocompleteStatus

Screen-reader-only status message that announces changes.

Prop

Type

All Base UI Autocomplete.Status props are forwarded via ...props.

AutocompleteArrow

Arrow element pointing from the popup to the trigger.

Prop

Type

All Base UI Autocomplete.Arrow props are forwarded via ...props.

AutocompleteBackdrop

Full-screen backdrop rendered behind the popup.

Prop

Type

All Base UI Autocomplete.Backdrop props are forwarded via ...props.

AutocompleteCollection

Re-export of AutocompletePrimitive.Collection for defining static item collections.

useAutocompleteFilter

Re-export of AutocompletePrimitive.useFilter hook for custom filtering logic.

Accessibility

Keyboard Interactions

Key	Action
`ArrowDown`	Opens the popup (if closed) or moves to the next item
`ArrowUp`	Opens the popup (if closed) or moves to the previous item
`Enter`	Accepts the highlighted item's value into the input
`Escape`	Closes the popup
`Home`	Moves to the first item in the list
`End`	Moves to the last item in the list
`Tab`	Closes the popup and moves focus to the next element

ARIA Attributes

The input has role="combobox" with aria-expanded indicating popup state.
aria-activedescendant tracks the currently highlighted item.
aria-autocomplete reflects the mode prop behavior.
AutocompleteContent has role="listbox" for the list of suggestions.
AutocompleteItem has role="option" with aria-disabled for disabled items.
AutocompleteGroup uses role="group" with aria-labelledby linked to the group label.
AutocompleteStatus provides a live region for screen reader announcements.

Autocomplete

On this page