Command

The command menu is a searchable list of actions and links, driven from the keyboard. Use it for a ⌘K palette, a quick switcher, or any search-then-select flow.

For a simple dropdown of options bound to a form field, use Select instead.

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>

Composition

Command
└── CommandContent
    ├── CommandInput
    └── CommandList
        └── CommandGroup
            ├── CommandGroupLabel
            ├── CommandSeparator
            └── CommandCollection
                └── CommandItem
                    └── CommandShortcut

Wrap the whole menu in CommandDialog to open it as a modal, and add CommandFooter below CommandContent for navigation hints.

Examples

Command Dialog

Wrap the menu in CommandDialog to open it as a ⌘K modal.

With Footer

Use CommandFooter to show keyboard navigation hints below the list.

Fuzzy Search

Use useFuzzyFilter to match across multiple fields and tolerate typos.

Virtualized

Use CommandVirtualizedList for large lists (100+ items); it only renders the items in view.

Key concepts:

1. Use useListVirtualizer hook - Handles scroll positioning, keyboard navigation, and item measurement. See useListVirtualizer docs for full API reference.
2. Use useCommandFilteredItems() inside Command - Call useCommandFilteredItems() in a child component of Command to get internally filtered items without manual filtering boilerplate.
3. Replace CommandList with CommandVirtualizedList - Accepts scrollRef and totalSize from the hook.
4. Pass virtualized and items on Command - Enables virtualized mode with your full item list.
5. Use useHighlightHandler - Pass a virtualizerRef to the child and use useHighlightHandler(virtualizerRef) on the parent so keyboard navigation scrolls to the highlighted item.

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 Command, and spread rootProps from useListVirtualizer. See useCommandFilter.

Accessibility

Keyboard navigation

The menu is operable entirely from the keyboard: type to filter, ↑/↓ to move between items, and Enter to select. autoHighlight="always" keeps an item highlighted at all times so Enter always has a target.

Label the input

CommandInput is the search field. Give it a placeholder, and when the menu opens outside a labeled CommandDialog, add an aria-label so its purpose is announced.

<CommandInput placeholder="Search commands…" aria-label="Search commands" />

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. Useful when you need manual control over filtering (e.g., with custom logic or server-side filtering).

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

useCommandFilteredItems

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

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

import { useCommandFilteredItems } from "@/registry/default/command/command";
 
function VirtualizedListContent() {
  // Must be called inside Command
  const filteredItems = useCommandFilteredItems<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 command lists using TanStack Virtual. Abstracts scroll handling, item positioning, and keyboard navigation.

See useListVirtualizer for full documentation and API reference.