CommandPalette
StableA search box and a list of actions in a modal window. Type to narrow the list, then press Enter.
Also known as command menu, command k, cmd k, spotlight
Install with npm install @tattva/ui (setup), or copy the code from the kit in Downloads.
Grouped commands opened by a button
Last command: Nothing yet
const commands: PaletteCommand[] = [
{ id: "new", label: "New chat", group: "Create", icon: <PlusIcon width={16} height={16} />, shortcut: "N", keywords: ["start", "conversation"], onSelect: () => setLast("New chat") },
{ id: "file", label: "Open file", group: "Create", hint: "Pick a file from your project", icon: <FileIcon width={16} height={16} />, onSelect: () => setLast("Open file") },
{ id: "search", label: "Search chats", group: "Go to", icon: <SearchIcon width={16} height={16} />, shortcut: "/", onSelect: () => setLast("Search chats") },
{ id: "settings", label: "Settings", group: "Go to", icon: <SettingsIcon width={16} height={16} />, keywords: ["preferences"], onSelect: () => setLast("Settings") },
{ id: "undo", label: "Undo last change", group: "Go to", icon: <UndoIcon width={16} height={16} />, disabled: true, onSelect: () => setLast("Undo") },
];
function Example() {
const [open, setOpen] = useState(false);
const [last, setLast] = useState("Nothing yet");
return (
<div className="flex flex-col items-start gap-2 text-body leading-5 text-fg">
<Button variant="secondary" onClick={() => setOpen(true)}>Open commands <Kbd className="ml-1">Ctrl K</Kbd></Button>
<p aria-live="polite" className="text-fg-muted">Last command: {last}</p>
<CommandPalette open={open} onClose={() => setOpen(false)} label="Commands" placeholder="Type a command…" commands={commands} />
</div>
);
}Commands under a group name get a heading. Typing narrows the list, matches at the start of a label come first, and a disabled command is shown but skipped by the arrow keys.
When to use it
Gives quick, keyboard-first access to many actions without a menu for each. Typing narrows the list and Enter runs the top choice.
Made of: Backdrop · Panel · Search field · Esc hint · Group heading · Option (icon, label, hint, shortcut) · Empty message
Use it for
- An app with many actions that people would rather type than hunt for.
- Jumping between places, or running an action from the keyboard.
- Showing shortcuts people can learn over time.
Do and avoid
Do
- Add a visible button that opens it, as well as any shortcut.
- Group commands under short headings.
- Add keywords for the other names people might type.
- Show a shortcut only when it really works.
- Keep labels short and start them with a verb or a place.
Avoid
- Do not make it the only way to reach an action.
- Do not register a shortcut inside it. Your app owns that.
- Do not use it for a form or a confirm. Use a Dialog.
- Do not put long text or controls inside an option.
- Do not give two commands the same label.
On a phone
- The palette fills the width with a 12px margin and sits at the top, taking up to the full screen height; from 640px it is centered lower and capped at 30rem.
- The search field is 16px so the page does not zoom, the Esc hint is hidden on a phone, and results scroll inside the list.
- Result rows are 44px tall on a touch screen, and the shortcut hints on each row are hidden on a phone.
- There is no keyboard shortcut to open it on a phone, so give people a button that opens it.
Properties
| Prop | Type | Default | Description |
|---|---|---|---|
| openrequired | boolean | none | Whether the palette is showing. Your code owns it. The search text resets each time it opens. |
| onCloserequired | () => void | none | Called on Escape, a click on the backdrop, and after a command is chosen (just before its onSelect). |
| commandsrequired | PaletteCommand[] | none | The actions. Each has id, label, onSelect, and optionally group, hint, icon, shortcut, keywords and disabled. |
| commands[].idrequired | string | none | Unique key for the command. |
| commands[].labelrequired | string | none | The name shown and searched. Matches at the start rank first. |
| commands[].group | string | none | Heading it is listed under. Commands without a group sit above the headings. |
| commands[].hint | string | none | Small helper text under the label. |
| commands[].icon | ReactNode | none | Shown before the label. Hidden from screen readers. |
| commands[].shortcut | string | none | Shown as a key hint. Display only. |
| commands[].keywords | string[] | none | Extra words that find the command. |
| commands[].disabled | boolean | none | Shown dimmed, marked aria-disabled, skipped by the arrow keys and ignored on click. |
| commands[].onSelectrequired | () => void | none | Runs when the command is chosen with Enter or a click. |
| placeholder | string | "Type a command…" | Hint text in the search field. |
| emptyText | string | "No matching commands" | Shown when nothing matches. |
| labelrequired | string | none | Accessible name of the dialog, the search field and the list. |
| className | string | none | Classes added to the panel. |
"Show code under the preview gives the code for the example on the stage."
States
States this part has beyond its default look. Build each one your screen can reach. States set by a property are in the Code tab.
- closed
- With open false nothing is drawn. The search text and active option reset the next time it opens.
- empty
- When no command matches the typed text, or none are passed, the empty text is shown and the result count says No results.
- active option
- One option is highlighted and named by aria-activedescendant. Arrow keys, Home, End and the pointer move it.
- disabled option
- A command with disabled is dimmed, marked aria-disabled, skipped by the arrow keys and ignored on click.
- filtered
- Once text is typed, the list is narrowed and ranked, with label-prefix matches first, and the count is announced.
Tokens
Change one of these and every part that uses it follows.
--surface-raised--surface-hover--border--scrim--shadow-lg--fg--fg-muted--fg-subtle--dur-base--focus-ring--radius-overlay
Built in
- The search field is a combobox with aria-expanded, aria-controls and aria-activedescendant. The list is a listbox with options, and groups are labelled by their headings.
- Focus stays in the search field. Arrow Up and Down move the active option and wrap round. Home and End jump to the first and last. Enter runs the active command and closes. Escape closes.
- Typing filters by label, keywords and group. The count ("5 results") is announced in a polite live region.
- It is a native modal dialog, so the page behind is inert. Focus returns to the element that opened it when it closes, and the page does not scroll behind it.
- The active option scrolls into view inside the list.
- Options are 44px tall on touch screens. The active option also gets an outline in forced-colors mode.
- Movement only plays when motion is not reduced.
What you need to do
- Give it a label that says what it does, such as "Commands".
- Add a visible button that opens it. A shortcut alone does not help people who cannot use the keyboard shortcut.
- Wire your shortcut yourself, for example Ctrl or Cmd plus K on the document, and call preventDefault on it.
- Make each shortcut shown in a command real. The palette only displays it.
- Keep command labels short and unique, because they are the options' names.
Built toward WCAG 2.2 AA and checked automatically; no independent audit yet. Read the accessibility guide