CommandPalette

The application owns the items and what choosing one does.

• open opens the palette, such as from a shortcut and from a visible control.
• onOpenChange receives false when Esc, a press on the backdrop or a choice closes it, and why, as a dialog's does: escape-key, outside-press, or item-press for a choice.
• The application filters and ranks the items itself, from the text in inputValue and onInputValueChange, and clears that text as the palette closes.
• onAction runs the chosen item, and closeOnAction, true by default, closes the palette after it.
• aria-label names the dialog, its search field and its list.
• placeholder shows in the empty field.
• suggestedItems show in place of items while the field is empty, and the empty state in place of the list when there are no options.

Items

Each CommandPaletteItem has an id and a label, with textValue for a label that isn't plain text.

• description is muted text under the label, such as a folder.
• icon is a decorative icon before it.
• end is content at the end, such as a Kbd shortcut or a Badge.
• disabled shows an item that can't be chosen.
• group names its group, whose heading shows where the group changes between items, such as Recently opened while the query is empty.

Suggestions and the empty state

suggestedItems show while the field is empty, or holds only spaces, in place of items, such as recent documents or suggested pages with a group heading; they are options like any other, highlighted, chosen with Enter or Ctrl+Enter and passed to onAction.

With no options, the empty state shows in place of the list as the polite status: one muted line at an option's height, its title and then its description after a dot, so the palette keeps about its height as results come and go.

• While the field is empty: Type to search, with no description; emptyDescription says what the palette finds.
• When the text finds nothing: No results, and a hint that quotes the trimmed text.
• While results load: the loading label, with a spinner at the search field's end, which also shows while results already found stay.
• emptyLabel and emptyDescription replace the title and the description in either state, null or false hiding the description, and emptyIcon puts an icon at the start of the line, where an option's sits, such as an error icon. Pass a value that depends on the query to change one state only.
• The icon is decorative and hidden from assistive technology; the title and description are announced.

const typed = query.trim() !== '';

<CommandPalette
  aria-label="Go to document"
  inputValue={query}
  onInputValueChange={setQuery}
  items={matches}
  // Recent documents, each with group: 'Recently opened'.
  suggestedItems={recent}
  emptyLabel={typed ? 'No matching documents' : undefined}
  emptyDescription={typed ? undefined : 'Find a document by its name or folder.'}
  {...props}
/>;

Commands and key hints

onAction receives the item and { modifier }, true while Ctrl or Cmd was held, such as to open beside. hints show keys below the list as Kbd, such as { keys: ['Enter'], label: 'Open' }, and footer holds other content after them, as the RunCommand example does. A hint with Enter in its keys hides while there is no option to choose, as results load or when nothing matches.

<CommandPalette
  open={open}
  onOpenChange={setOpen}
  aria-label="Run a command"
  inputValue={query}
  onInputValueChange={setQuery}
  items={[
    { id: 'new', label: 'New document', icon: <IconNoteAdd />, end: <Kbd keys={['Ctrl', 'N']} /> },
    { id: 'automations', label: 'Create an automation', end: <Badge tone="primary">New</Badge> },
  ]}
  onAction={(item, { modifier }) => run(item.id, { beside: modifier })}
  hints={[{ keys: ['Enter'], label: 'Run' }]}
  footer="Shortcuts work anywhere in the workspace."
/>

The button that opens it

The button is a Button with variant="secondary", IconSearch as its startIcon, and a Kbd of the keys in its end slot, as the InSidebar example does.

• aria-hidden on the Kbd and aria-keyshortcuts on the button announce the shortcut once.
• Its onClick opens the palette.
• With fullWidth it fills its container, such as a NavigationDrawer's header.

<Button
  variant="secondary"
  fullWidth
  startIcon={<IconSearch />}
  end={<Kbd keys={[modifier.label, 'K']} aria-hidden />}
  aria-keyshortcuts={`${modifier.key}+K`}
  onClick={() => setOpen(true)}
>
  Search
</Button>

The shortcut

The application listens for the shortcut once, at its root, however many buttons show it, and opens the same palette the button does. It skips an event whose defaultPrevented is set, so a key press that something else already handled, such as an editor's own shortcut, is left alone.

useModifierKey(), on Kbd's page, gives the platform's modifier.

• Its key, Meta or Control, for aria-keyshortcuts and the listener.
• Its label, ⌘ or Ctrl, for Kbd.
• It is Ctrl on the server and while the page hydrates, so server-rendered markup matches, and becomes ⌘ on Apple platforms right after.
• Don't read navigator while rendering: it doesn't exist on the server, and markup that differs from the server's fails to hydrate.

const modifier = useModifierKey();

useEffect(() => {
  const onKeyDown = (event: KeyboardEvent) => {
    const pressed =
      modifier.key === 'Meta' ? event.metaKey && !event.ctrlKey : event.ctrlKey && !event.metaKey;
    if (event.defaultPrevented || !pressed || event.altKey || event.shiftKey) return;
    if (event.key.toLowerCase() !== 'k') return;
    event.preventDefault();
    setSearchOpen((open) => !open);
  };
  addEventListener('keydown', onKeyDown);
  return () => removeEventListener('keydown', onKeyDown);
}, [modifier.key]);

Icon only

In a narrow header, the button is an IconButton with variant="ghost", aria-label="Search" and the same aria-keyshortcuts, inside a Tooltip with side="bottom" whose content holds the label and the Kbd, as the IconOnly example does.

<Tooltip
  side="bottom"
  content={
    <Row render={<span />} align="center" gap={2}>
      Search <Kbd keys={[modifier.label, 'K']} />
    </Row>
  }
>
  <IconButton
    variant="ghost"
    icon={<IconSearch />}
    aria-label="Search"
    aria-keyshortcuts={`${modifier.key}+K`}
    onClick={() => setOpen(true)}
  />
</Tooltip>

The palette is env-command-palette: its search field, env-command-palette-search, a large ghost TextField kept solid on the frosted palette, with its input, env-command-palette-input, and the close button shown under a coarse pointer, env-command-palette-close, in env-command-palette-header, the group headings, env-command-palette-group-label, the items, env-command-palette-item, the key hints in env-command-palette-footer, and the empty state, env-command-palette-status with data-empty: its icon, env-command-palette-empty-icon, title, env-command-palette-empty-title, and description, env-command-palette-empty-description. className, style, ref and data attributes reach the surface.

The button that opens it is Button's: env-button, its icon, env-button > env-icon, its label, and the keys in its end slot, env-button-end. The icon-only button is an env-icon-button in a tooltip.

Its popup is frosted, as every popup is: --env-popup-opacity, --env-popup-blur and --env-popup-shadow, set on a theme, change it, as Popover describes.