Shadcn Autocomplete for React and Tailwind

Installation

bunx --bun shadcn@latest add https://kit.dev/r/autocomplete.json

pnpm dlx shadcn@latest add https://kit.dev/r/autocomplete.json

npx shadcn@latest add https://kit.dev/r/autocomplete.json

yarn shadcn@latest add https://kit.dev/r/autocomplete.json

bun add @ark-ui/react tailwind-variants lucide-react

pnpm add @ark-ui/react tailwind-variants lucide-react

npm install @ark-ui/react tailwind-variants lucide-react

yarn add @ark-ui/react tailwind-variants lucide-react

"use client";

import type { Combobox as ArkCombobox } from "@ark-ui/react/combobox";
import type React from "react";
import {
  Combobox,
  ComboboxClear,
  ComboboxContent,
  ComboboxContext,
  ComboboxControl,
  ComboboxEmpty,
  ComboboxGroup,
  ComboboxGroupLabel,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
  ComboboxRootProvider,
  ComboboxTrigger,
  useCombobox,
  useComboboxContext,
} from "@/components/ui/combobox";
import { Separator } from "@/components/ui/separator";

export const useAutocomplete = useCombobox;
export const useAutocompleteContext = useComboboxContext;
export const AutocompleteContext: typeof ComboboxContext = ComboboxContext;

export const AutocompleteRootProvider: ArkCombobox.RootProviderComponent = (
  props
) => <ComboboxRootProvider data-slot="autocomplete" {...props} />;

export const Autocomplete: ArkCombobox.RootComponent = (props) => (
  <Combobox
    allowCustomValue
    data-slot="autocomplete"
    inputBehavior="autocomplete"
    {...props}
  />
);

export const AutocompleteControl = (
  props: React.ComponentProps<typeof ComboboxControl>
) => <ComboboxControl data-slot="autocomplete-control" {...props} />;

export const AutocompleteInput = (
  props: React.ComponentProps<typeof ComboboxInput>
) => {
  const { showClear = false, showTrigger = false, ...rest } = props;

  return (
    <ComboboxInput
      data-slot="autocomplete-input"
      showClear={showClear}
      showTrigger={showTrigger}
      {...rest}
    />
  );
};

export const AutocompleteGroupLabel = (
  props: React.ComponentProps<typeof ComboboxGroupLabel>
) => <ComboboxGroupLabel data-slot="autocomplete-group-label" {...props} />;

export const AutocompleteItem = (
  props: React.ComponentProps<typeof ComboboxItem>
) => <ComboboxItem data-slot="autocomplete-item" {...props} />;

export const AutocompleteContent = (
  props: React.ComponentProps<typeof ComboboxContent>
) => <ComboboxContent data-slot="autocomplete-content" {...props} />;

export const AutocompleteTrigger = (
  props: React.ComponentProps<typeof ComboboxTrigger>
) => <ComboboxTrigger data-slot="autocomplete-trigger" {...props} />;

export const AutocompleteClear = (
  props: React.ComponentProps<typeof ComboboxClear>
) => <ComboboxClear data-slot="autocomplete-clear" {...props} />;

export const AutocompleteGroup = (
  props: React.ComponentProps<typeof ComboboxGroup>
) => <ComboboxGroup data-slot="autocomplete-group" {...props} />;

export const AutocompleteEmpty = (
  props: React.ComponentProps<typeof ComboboxEmpty>
) => <ComboboxEmpty data-slot="autocomplete-empty" {...props} />;

export const AutocompleteList = (
  props: React.ComponentProps<typeof ComboboxList>
) => <ComboboxList data-slot="autocomplete-list" {...props} />;

export const AutocompleteCollection = (
  props: React.ComponentProps<typeof ComboboxList>
) => <ComboboxList data-slot="autocomplete-collection" {...props} />;

export const AutocompleteSeparator = (
  props: React.ComponentProps<typeof Separator>
) => <Separator data-slot="autocomplete-separator" {...props} />;

Anatomy

Autocomplete
├── AutocompleteInput
│   ├── AutocompleteControl (built in)
│   ├── input
│   ├── AutocompleteTrigger (optional)
│   └── AutocompleteClear (optional)
└── AutocompleteContent
    ├── AutocompleteEmpty
    └── AutocompleteList
        └── AutocompleteGroup
            ├── AutocompleteGroupLabel
            └── AutocompleteItem

AutocompleteContent portals the list and includes the positioner. AutocompleteItem includes the check indicator.

Use Field for the visible label rather than a separate autocomplete label part.

Usage

Autocomplete is Combobox with allowCustomValue and inputBehavior="autocomplete". Pass a collection and filter as the user types.

import { useListCollection } from "@ark-ui/react/collection";
import { useFilter } from "@ark-ui/react/locale";
import {
  Autocomplete,
  AutocompleteContent,
  AutocompleteEmpty,
  AutocompleteGroup,
  AutocompleteInput,
  AutocompleteItem,
  AutocompleteList,
} from "@/components/ui/autocomplete";

const { contains } = useFilter({ sensitivity: "base" });
const { collection, filter } = useListCollection({
  initialItems: [
    { label: "Apple", value: "apple" },
    { label: "Banana", value: "banana" },
  ],
  filter: contains,
});

<Autocomplete
  collection={collection}
  onInputValueChange={({ inputValue }) => filter(inputValue)}
>
  <AutocompleteInput placeholder="e.g. Apple" />
  <AutocompleteContent>
    <AutocompleteEmpty />
    <AutocompleteList>
      {collection.items.map((item) => (
        <AutocompleteItem item={item} key={item.value}>
          {item.label}
        </AutocompleteItem>
      ))}
    </AutocompleteList>
  </AutocompleteContent>
</Autocomplete>

Controlled

Control the selected value with value and onValueChange. Selected values are always a string[].

Root Provider

Use useAutocomplete with AutocompleteRootProvider when you need the API outside the tree. Pass machine options (collection, allowCustomValue, inputBehavior, …) to useAutocomplete(), not to the provider.

States

Invalid

Disabled

Sizes

Size is set on AutocompleteInput. sm is h-7, md is h-8, lg is h-9.

Small

Medium

Large

Examples

Auto highlight

Highlight the first matching item as the user types with inputBehavior="autohighlight". This overrides Autocomplete’s default autocomplete behavior.

Inline autocomplete

Autocomplete already sets inputBehavior="autocomplete": arrow keys complete the input with the highlighted item. Pair it with a startsWith filter for best results.

Group

Group related items with groupBy on the collection and collection.group() when rendering. AutocompleteGroup accepts a heading for the label.

With Field

Field wires the label, helper text, and error text to the control.

Context

Read selected state with AutocompleteContext or useAutocompleteContext.

Links

Render items as links with asChild. Use selectionBehavior="preserve" so choosing a link does not replace the input value.

Rehydrate

When defaultValue or value is set before the collection loads, call syncSelectedItems() once the items are available so the input shows the selected label.

Highlight text

Highlight the matching query in each item with Highlight.

Dynamic

Build the collection from the current input. Useful for email-style suggestions.

Creatable

Let users add a value that is not in the list. Upsert a temporary “create” item while typing, then replace it on select.

Multiple selection

Set multiple to select more than one item. Selection behavior becomes clear, so render selected items outside the input.

Async search

Load options from an async source with useAsyncList. Filter only on reason === "input-change" so highlighting and selection do not refetch.

Custom object

Map custom objects with itemToString and itemToValue on useListCollection.

Limit results

Pass limit to useListCollection to cap how many items are rendered.

With clear button

Pass showClear to AutocompleteInput. The clear control is shown when the input is not empty.

With trigger

Pass showTrigger to show the chevron that opens the list. Autocomplete hides it by default.

With start icon

Put an InputGroupAddon as a child of AutocompleteInput. Decorative icons should be aria-hidden="true".

Guides

Autocomplete vs Combobox

Use Select when there is no search. Use Command for a command palette. Use Tags Input when the value is a list of removable tags.

Collections

Items live in an Ark collection, not a loose items prop on the root.

const { contains } = useFilter({ sensitivity: "base" });
const { collection, filter } = useListCollection({
  initialItems,
  filter: contains,
});

<Autocomplete
  collection={collection}
  onInputValueChange={({ inputValue }) => filter(inputValue)}
>

Call filter(inputValue) from onInputValueChange. Render collection.items (or collection.group() when grouping).

Custom objects

By default the collection expects { label, value }. Map other shapes with itemToString and itemToValue:

const { collection } = useListCollection({
  initialItems: [
    { country: "Canada", code: "CA", flag: "🇨🇦" },
  ],
  itemToString: (item) => item.country,
  itemToValue: (item) => item.code,
});

Type safety

Autocomplete is typed as Ark’s RootComponent, so onValueChange infers item types from the collection:

<Autocomplete
  collection={collection}
  onValueChange={(e) => {
    // e.items is T[]
    console.log(e.items);
  }}
>

Large datasets

Prefer limit on useListCollection so only a slice is in the DOM:

const { collection } = useListCollection({
  initialItems: items,
  limit: 10,
});

For very large lists, pass scrollToIndexFn and virtualize the list (for example with TanStack Virtual). Keyboard navigation needs that scroll helper.

Router links

Set navigate on the root when items are links, so in-app routing runs instead of a full navigation:

<Autocomplete
  collection={collection}
  navigate={(details) => {
    router.push(details.node.href);
  }}
>

NavigateDetails is { value: string; node: HTMLAnchorElement; href: string }.

Available size

The positioner (built into AutocompleteContent) exposes CSS variables you can use on the list:

Example: match the input width and cap height to the viewport.

<AutocompleteContent className="w-(--reference-width) max-h-[min(24rem,calc(var(--available-height)-100px))]" />

Multiple selection

When multiple is true, selectionBehavior is set to clear. Render selectedItems from context above the input (chips, tags, or a summary). Do not rely on the input to show every selected value.

API Reference

shadcn.io wraps Ark UI Combobox. Defaults below are shadcn.io Autocomplete values. They differ from Ark Combobox for allowCustomValue (true here), inputBehavior (autocomplete here, none in Ark), openOnClick (true here, false in Ark), and lazyMount / unmountOnExit (true here, false in Ark).

asChild merges props onto a single child element.

Autocomplete

Root. Renders a div. Requires a collection.

AutocompleteInput

Composed control: Input Group wrapping the searchable input, optional trigger, and optional clear button. Children render as start addons (icons, text). Renders inside AutocompleteControl.

Native input attributes (type, aria-label, autoComplete, …) pass through to the input.

The composed control is Combobox’s input group, so the wrapper keeps Combobox slots (combobox-control, combobox-trigger, combobox-clear). The input itself is autocomplete-input.

AutocompleteControl

Optional wrapper for custom layouts. AutocompleteInput already includes it.

AutocompleteTrigger

Opens the list. Used by AutocompleteInput when showTrigger is true. Renders a button.

AutocompleteClear

Clears the input. Used by AutocompleteInput when showClear is true. Renders a button.

AutocompleteContent

Portaled list surface. Includes the positioner. Renders a div.

AutocompleteList

Wraps the options. Renders a div.

AutocompleteItem

A single option. Always uses persistFocus so pointer leave does not clear highlight. Includes a check indicator unless showIndicator={false}. Renders a div.

The indicator is not a separate export.

AutocompleteGroup

Groups related options. Pass heading to render AutocompleteGroupLabel.

AutocompleteGroupLabel

Label for a group. Usually created by heading on AutocompleteGroup. Renders a div.

AutocompleteEmpty

Shown when the filtered collection has no items. Default children: No results found.

AutocompleteSeparator

Separator for custom list layouts.

AutocompleteRootProvider

Root alternative that takes the API from useAutocomplete. Renders a div.

Pass collection, allowCustomValue, inputBehavior, and other machine options to useAutocomplete(), not to AutocompleteRootProvider. To match Autocomplete, pass allowCustomValue: true and inputBehavior: "autocomplete".

useAutocomplete

Creates the autocomplete API for AutocompleteRootProvider. Accepts the same options as Autocomplete except layout-only props.

const autocomplete = useAutocomplete({
  allowCustomValue: true,
  collection,
  inputBehavior: "autocomplete",
  onInputValueChange: (details) => filter(details.inputValue),
});

autocomplete.focus();

AutocompleteContext / useAutocompleteContext

Render-prop or hook access to autocomplete state. Use inside Autocomplete or AutocompleteRootProvider.

AutocompleteContext children: (context) => ReactNode.

Accessibility

Complies with the Combobox WAI-ARIA design pattern. Label the input with Field (FieldLabel) or aria-label on AutocompleteInput. Keep AutocompleteEmpty so a filtered list is not a blank popup.

Keyboard support