Command

A searchable list of actions for command palettes and quick switchers.

Loading...

Anatomy

<Command.Root>
  <Command.Label />
  <Command.Control>
    <Command.Input />
  </Command.Control>
  <Command.List>
    <Command.ItemGroup>
      <Command.ItemGroupLabel />
      <Command.Item>
        <Command.ItemText />
      </Command.Item>
    </Command.ItemGroup>
  </Command.List>
  <Command.Empty />
</Command.Root>

Examples

Basic

Pass a collection to Command.Root and render the filtered items from Command.Context. Typing filters the items, the arrow keys, Home, and End move the highlight while focus stays in the input, and Enter or a click calls onSelect.

Dialog

Put the command inside a Dialog to build a command palette. Open it with a keyboard shortcut using useHotkey, and give the dialog content an aria-label.

Groups

Use groupBy on the collection and render collection.group() with ItemGroup and ItemGroupLabel. Groups with no matching items are not rendered. Disabled items are skipped by the keyboard.

Empty State

Command.Empty renders its children when no item matches the input.

Keywords

Items are fuzzy-matched on their text and an optional keywords array, best match first.

{ value: 'settings', label: 'Open settings', keywords: ['preferences', 'config'] }

Pages

Use createPageListCollection and give an item a parent to put it on that item's page. Selecting the parent opens the page, Backspace in an empty input goes up, and typing also searches nested pages. Pass page to start on one.

const collection = createPageListCollection({
  items: [
    { value: 'theme', label: 'Change theme' },
    { value: 'dark', label: 'Dark', parent: 'theme' },
    { value: 'light', label: 'Light', parent: 'theme' },
  ],
  page: 'theme',
})

Render breadcrumbs with path and a result's location with getAncestors. To make Escape go back before the dialog closes, call back() from onEscapeKeyDown:

const command = useCommand({ collection })

<Dialog.Root
  onEscapeKeyDown={(event) => {
    if (command.canGoBack) {
      event.preventDefault()
      command.back()
    }
  }}
>
  {/* ... */}
  <Command.RootProvider value={command}>{/* ... */}</Command.RootProvider>
</Dialog.Root>

Async

Load items with useAsyncList, call setFilter as the input changes, and pass isLoading to loading. Pass a filter that returns every item, since the server already filtered them.

Root Provider

Use the useCommand hook with RootProvider to control the command from outside, for example to clear the input.

Guides

Custom filtering

Pass filter to replace the fuzzy search. It returns the matching items in the order to show them.

<Command.Root
  collection={collection}
  filter={(items, query) => items.filter((item) => item.label.toLowerCase().startsWith(query.toLowerCase()))}
/>

Accessibility

The input is a combobox that controls the listbox and points to the highlighted option with aria-activedescendant, so focus never leaves the input. Result counts are announced to screen readers. Label the command with Command.Label, and label the dialog when you render it in one.

API Reference

Props

Context