Command
A searchable list of actions for command palettes and quick switchers.
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.