Combobox

Preview

Installation

npx shadcn@latest add @cubby-ui/combobox

Usage

import {
  Combobox,
  ComboboxClear,
  ComboboxInput,
  ComboboxInputWrapper,
  ComboboxItem,
  ComboboxList,
  ComboboxTrigger,
  ComboboxPopup,
  ComboboxEmpty,
  ComboboxLabel,
} from "@/components/ui/cubby-ui/combobox";

<Combobox>
  <ComboboxLabel />
  <ComboboxInputWrapper>
    <ComboboxInput />
    <ComboboxClear />
    <ComboboxTrigger />
  </ComboboxInputWrapper>
  <ComboboxPopup>
    <ComboboxEmpty />
    <ComboboxList>
      <ComboboxItem />
    </ComboboxList>
  </ComboboxPopup>
</Combobox>

Examples

Creatable

Allow users to create new options.

Multiple Selection

Select multiple options from the combobox.

Input Inside Popup

Place the search input within the dropdown popup.

Async Search

Load options from a remote source by fetching on input changes. The useAsyncCombobox hook handles request cancellation, loading states, and keeps the selected value visible while new results stream in.

Async Search (Multiple)

Async search with multiple selection support. Selected items remain visible in the dropdown while searching for new matches.

Grouped

Organize options into logical groups with sticky headers.

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. Use useComboboxFilteredItems() inside Root - Call useComboboxFilteredItems() in a child component of Combobox to get internally filtered items without manual filtering boilerplate.
3. Replace ComboboxList with ComboboxVirtualizedList - 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 ComboboxItem since virtualized items are absolutely positioned and the virtualizer handles padding.

API Reference

The Combobox component is built on top of Base UI's Combobox. 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 Combobox documentation.

Props

ComboboxPopup

Dropdown container for the option list with positioning. Composes Base UI's Combobox.Positioner and Combobox.Popup. Props are forwarded to Combobox.Popup.

ComboboxList

Scrollable list of selectable options. Wraps Base UI's Combobox.Listbox.

ComboboxVirtualizedList

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

Hooks

useComboboxFilteredItems

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

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

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