Autocomplete

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>

Examples

Async Loading

Fetch suggestions asynchronously from an API.

Auto Highlight

Automatically highlight the first suggestion.

Clearable Input

Add a clear button to reset the input value.

Fuzzy Search

Enable fuzzy matching for more flexible searching.

Grouped Options

Organize suggestions into categories.

Inline Suggestions

Display suggestions inline within the input.

Limited Results

Limit the number of displayed suggestions.

Virtualized

Use virtualization for large lists (100+ items) to maintain smooth performance. Only renders items visible in the viewport, dramatically reducing DOM nodes.

Key concepts:

1. Use useListVirtualizer hook - Handles scroll positioning, keyboard navigation, and item measurement. See useListVirtualizer docs for full API reference.
2. External filtering - Compute filteredItems yourself and pass filter={null} to Autocomplete.Root. The hook needs both arrays to calculate proper aria attributes.
3. Replace AutocompleteList with AutocompleteVirtualizedList - Accepts scrollRef and totalSize from the hook.
4. Spread rootProps - Contains virtualization state for Base UI integration.
5. Override item margins - Pass className="mt-0! mb-0!" to AutocompleteItem since virtualized items are absolutely positioned and the virtualizer handles padding.

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

AutocompletePositioner

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

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],
);

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.