CommandPalette

A keyboard-driven search surface for actions and pages, with grouped results, icons, and shortcut hints.

When to use

• A global ⌘K launcher for power users: jump to pages, run actions, change preferences.
• A searchable action list inside a dialog or empty state.
• Not for picking a value in a form: use Combobox or Select. For a short fixed menu use DropdownMenu.

Usage

import { CommandPalette } from "@/components/iris/command-palette/command-palette";

h(CommandPalette, {
  items: [
    { id: "new-page", label: "New page", group: "Actions", shortcut: "⌘ N" },
    {
      id: "tokens",
      label: "Project tokens",
      description: "Create and rotate tokens",
      group: "Navigate",
      keywords: ["mcp", "cli"],
    },
  ],
  placeholder: "Search documents and commands",
  onSelect: (item) => run(item.id),
  autoFocus: true,
});

Props

Prop	Type	Default	Description
items	CommandItem[]	—	Required. { id, label, description?, group?, keywords?, icon?, shortcut? }. Items without group fall under "Actions".
placeholder	string	"Search commands"	Search field placeholder.
onSelect	(item: CommandItem) => void	—	Called on click or Enter.
onClose	() => void	—	When set, shows an Esc button that calls it.
label	string	"Command palette"	Accessible name of the search field.
autoFocus	boolean	false	Focus the search field on mount, for a palette opened on demand.

Notes

• The palette renders inline; wrap it in a Dialog (or your own layer) for a modal ⌘K experience. It has no open state of its own.
• Search matches label, description, group, and keywords. Up/Down/Home/End move the highlight, Enter runs it (or the top match after typing), Escape clears the query and then calls onClose. The input uses aria-activedescendant over a listbox.
• It listens for ⌘K / Ctrl+K on the document and focuses its search field, so mount only one palette at a time.
• Filtering glides rows into place when they move a short distance and snaps for long jumps; the frame height morphs. Reduced motion removes the glide.
• Reads --surface, --hover, --line, --line-soft, --ink, --ink-3.