Autocomplete

Autocomplete is a text input that suggests matching options as the user types, while still accepting free-form text. Use it for search fields, tag entry, or any input where suggestions speed things up but the value isn't restricted to the list.

For selecting a single required value from a fixed list, use Combobox instead.

Preview

Installation

npx shadcn@latest add @cubby-ui/autocomplete

Usage

import {
  AutocompleteEmpty,
  AutocompleteInput,
  AutocompleteItem,
  AutocompleteList,
  AutocompletePopup,
  AutocompletePortal,
  AutocompletePositioner,
  AutocompleteRoot,
} from "@/components/ui/cubby-ui/autocomplete";

<AutocompleteRoot>
  <AutocompleteInput />
  <AutocompletePortal>
    <AutocompletePositioner>
      <AutocompletePopup>
        <AutocompleteEmpty />
        <AutocompleteList>
          <AutocompleteItem />
        </AutocompleteList>
      </AutocompletePopup>
    </AutocompletePositioner>
  </AutocompletePortal>
</AutocompleteRoot>

Composition

AutocompleteRoot
├── AutocompleteInput
│   ├── AutocompleteTrigger
│   └── AutocompleteClear
└── AutocompletePortal
    └── AutocompletePositioner
        └── AutocompletePopup
            ├── AutocompleteEmpty
            └── AutocompleteList
                ├── AutocompleteGroup
                │   ├── AutocompleteGroupLabel
                │   └── AutocompleteItem
                └── AutocompleteItem

Examples

Async Loading

Fetch suggestions from an API as the query changes.

Auto Highlight

Set autoHighlight on AutocompleteRoot to highlight the first suggestion automatically.

Clearable Input

Set showClear on AutocompleteInput to add a button that resets the value.

Trigger and Clear

Set showTrigger and showClear on AutocompleteInput to show a popup toggle and a clear button. Same anatomy as the Combobox.

Fuzzy Search

Pass a fuzzy matcher as the filter to match suggestions loosely.

Grouped Options

Wrap items in AutocompleteGroup with an AutocompleteGroupLabel to organize them into categories.

Inline Suggestions

Set mode="both" on AutocompleteRoot to complete the input inline with the highlighted suggestion.

Limited Results

Use limit on AutocompleteRoot to cap the number of suggestions shown.

Virtualized

Use virtualization for large lists (100+ items) so only the items in view are rendered, keeping the list smooth.

Key concepts:

1. Use useListVirtualizer hook - Handles scroll positioning, keyboard navigation, and item measurement. See useListVirtualizer docs for full API reference.
2. Use useAutocompleteFilteredItems() inside Root - Call useAutocompleteFilteredItems() in a child component of AutocompleteRoot to get internally filtered items without manual filtering boilerplate.
3. Replace AutocompleteList with AutocompleteVirtualizedList - Accepts scrollRef and totalSize from the hook.
4. Pass virtualized and items on Root - Enables virtualized mode with your full item list.
5. Use useHighlightHandler - Pass a virtualizerRef to the child and use useHighlightHandler(virtualizerRef) on Root so keyboard navigation scrolls to the highlighted item.
6. Override item margins - Pass className="mt-0! mb-0!" to AutocompleteItem since virtualized items are absolutely positioned and the virtualizer handles padding.

Manual filtering still works. If you need custom filter logic (fuzzy search, server-side filtering), you can still compute filteredItems externally, pass filter={null} to Autocomplete.Root, and spread rootProps from useListVirtualizer. See useAutocompleteFilter.

Elevated Variant

On a Card, Dialog, or popover surface, the opaque default input collapses into its parent. Use variant="elevated" on AutocompleteInput for a translucent overlay that adapts to the substrate. See the Surfaces docs.

Form Integration

Use Field with FieldLabel for labeling. See the Forms guide for more patterns.

API Reference

The Autocomplete component is built on top of Base UI's Autocomplete. All Base UI props are supported. The documentation below only covers custom props and modified defaults specific to our implementation.

For the complete Base UI API, see the Base UI Autocomplete documentation.

Props

AutocompleteInput

Text input with optional trigger and clear buttons. When showTrigger or showClear is enabled, wraps the input inside an Autocomplete.InputGroup.

AutocompletePositioner

Positions the suggestions dropdown relative to the input. Wraps Base UI's Autocomplete.Positioner.

AutocompletePopup

The popup container. Wraps Base UI's Autocomplete.Popup.

AutocompleteList

Scrollable container for suggestion items. Wraps Base UI's Autocomplete.List.

AutocompleteVirtualizedList

Virtualized scrollable container for large lists. Use with useListVirtualizer hook for optimal performance with 100+ items.

Utilities

highlightText

Highlights matching portions of text by wrapping them in <mark> tags. Useful for showing which parts of a suggestion match the user's input.

See highlightText for full documentation and API reference.

Hooks

useAutocompleteFilter

function useAutocompleteFilter(): {
  contains: (
    item: T,
    query: string,
    getItemLabel: (item: T) => string,
  ) => boolean;
  startsWith: (
    item: T,
    query: string,
    getItemLabel: (item: T) => string,
  ) => boolean;
  endsWith: (
    item: T,
    query: string,
    getItemLabel: (item: T) => string,
  ) => boolean;
};

Exposes Base UI's built-in filter matchers for external filtering. Required when using virtualization since you must compute filteredItems yourself.

Returns

import { useAutocompleteFilter } from "@/registry/default/autocomplete/autocomplete";
 
const { contains } = useAutocompleteFilter();
const getItemLabel = (item: Item | null) => item?.name ?? "";
 
const filteredItems = useMemo(
  () => items.filter((item) => contains(item, query, getItemLabel)),
  [contains, query],
);

useAutocompleteFilteredItems

function useAutocompleteFilteredItems<T>(): T[];

Returns the internally filtered items from the Autocomplete Root. Must be called inside AutocompleteRoot. Simplifies virtualized implementations by eliminating the need for manual query state, useDeferredValue, useFilter(), and useMemo filtering.

import { useAutocompleteFilteredItems } from "@/registry/default/autocomplete/autocomplete";
 
function VirtualizedListContent() {
  // Must be called inside AutocompleteRoot
  const filteredItems = useAutocompleteFilteredItems<MyItem>();
 
  const virtualizer = useListVirtualizer({
    items: allItems,
    filteredItems,
  });
  // ...
}

useFuzzyFilter

Provides fuzzy matching capabilities for flexible searching across multiple fields. Returns filter functions compatible with Base UI's Autocomplete.

See useFuzzyFilter for full documentation and API reference.

useListVirtualizer

Provides virtualization for large autocomplete lists using TanStack Virtual. Abstracts scroll handling, item positioning, and keyboard navigation.

See useListVirtualizer for full documentation and API reference.