Command

Preview

Installation

npx shadcn@latest add @cubby-ui/command

Usage

import {
  Command,
  CommandInput,
  CommandList,
  CommandGroup,
  CommandGroupLabel,
  CommandItem,
} from "@/components/ui/cubby-ui/command"

<Command>
  <CommandInput placeholder="Search..." />
  <CommandList>
    <CommandGroup>
      <CommandGroupLabel>Suggestions</CommandGroupLabel>
      <CommandItem>Calendar</CommandItem>
      <CommandItem>Search</CommandItem>
    </CommandGroup>
  </CommandList>
</Command>

Examples

Command Dialog

Display command menu in a modal dialog with keyboard shortcut support.

With Footer

Add footer content with keyboard navigation hints.

Fuzzy Search

Enable fuzzy matching for more flexible searching across multiple fields.

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 Command. The hook needs both arrays to calculate proper aria attributes.
3. Replace CommandList with CommandVirtualizedList - Accepts scrollRef and totalSize from the hook.
4. Spread rootProps - Contains virtualization state for Base UI integration.

import { useListVirtualizer } from "@/hooks/cubby-ui/use-list-virtualizer";
import { useCommandFilter } from "@/lib/cubby-ui/command";
 
// Helper to extract searchable text from items
const getItemLabel = (item: Item | null) => item?.name ?? "";
 
// 1. Set up filtering with deferred value for performance
const { contains } = useCommandFilter();
const deferredQuery = useDeferredValue(query);
const resolvedQuery =
  query === "" || deferredQuery === "" ? query : deferredQuery;
const filteredItems = useMemo(
  () => items.filter((item) => contains(item, resolvedQuery, getItemLabel)),
  [contains, resolvedQuery],
);
 
// 2. Initialize virtualizer
const {
  rootProps, // Spread on Command
  scrollRef, // Pass to CommandVirtualizedList
  measureRef, // Pass to each CommandItem
  totalSize, // Pass to CommandVirtualizedList
  virtualItems, // Array to map over
  getItem, // Get data for virtual item
  getItemStyle, // Get positioning styles
  getItemProps, // Get aria attributes
} = useListVirtualizer({
  items, // All items (for aria-setsize)
  filteredItems, // Items to display
  estimateSize: 40, // Item height in px
});
 
// 3. Render
<Command {...rootProps} filter={null} itemToStringValue={getItemLabel}>
  <CommandVirtualizedList
    scrollRef={scrollRef}
    totalSize={totalSize}
    nativeScroll
  >
    {virtualItems.map((virtualItem) => (
      <CommandItem
        key={virtualItem.key}
        ref={measureRef}
        value={getItem(virtualItem)}
        style={getItemStyle(virtualItem)}
        {...getItemProps(virtualItem)}
      >
        {getItem(virtualItem)?.name}
      </CommandItem>
    ))}
  </CommandVirtualizedList>
</Command>;

Filtering options:

• Default filtering: Use useCommandFilter for the same contains/startsWith/endsWith matchers as Command's built-in filter
• Fuzzy search: Use useFuzzyFilter for relevance-sorted results across multiple fields
• Server-side filtering: Pass the same array to both items and filteredItems
• Custom filtering: Use any filtering method (native .filter(), third-party libraries, etc.)

API Reference

The Command component is built on top of Base UI's Autocomplete and Dialog. 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

Command

Root component that manages command menu state and keyboard navigation. Wraps Base UI's Autocomplete.Root.

CommandList

Scrollable container for command items with empty state handling. Wraps Base UI's Autocomplete.List.

CommandVirtualizedList

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 command match the user's input.

See highlightText for full documentation and API reference.

Hooks

useCommandFilter

function useCommandFilter(): {
  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 { useCommandFilter } from "@/registry/default/command/command";
 
const { contains } = useCommandFilter();
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 command lists using TanStack Virtual. Abstracts scroll handling, item positioning, and keyboard navigation.

See useListVirtualizer for full documentation and API reference.