CommandPalette

When to useLink to "When to use"

• Products with many actions spread across menus and panels: inspectors, editors, database tools.

Use something else when:

• the actions belong to one button: a Menu
• people pick a value for a field: a Combobox

UsageLink to "Usage"

import { CommandPalette } from "@arshad-shah/cynosure";

<CommandPalette
  commands={[
    { id: "save", label: "Save file", group: "File", shortcut: ["Ctrl", "S"], keywords: ["write", "disk"] },
    { id: "preview", label: "Toggle preview", group: "View" },
  ]}
  onRun={(id) => actions[id]()}
/>

Mount it once near the root. It listens for its shortcut (mod+k by default) anywhere on the page, shadow roots included. A command's shortcut is only shown in the row; bind those keys with useHotkey.

Finding commandsLink to "Finding commands"

Every typed word must appear in the label or the keywords, in any order, and commands whose label starts with the first word come first. Each typed word is marked where it appears in a label (HighlightedText); the option is still named by its whole label. Before anything is typed, the commands run most recently come first under "Recent".

Before anything is typed, commands are listed under their group headings. Search results are one flat list in rank order, so each row shows its group as a small Badge between the label and the shortcut; recent commands, which mix groups, carry the tag too.

Your own searchLink to "Your own search"

filter(command, query) replaces the built-in search, for an app with its own fuzzy matcher. It is called for each command while there is a query (trimmed), and answers with a match, true, or null:

<CommandPalette commands={commands} onRun={run} filter={(command, query) => fuzzyMatch(query, command.label)} />

• A match { score, positions } keeps the command. Lower scores come first, as fuzzy matchers score them; ties, and matches without a score, keep the order of commands. positions are the indices of the matched characters in the label, and exactly those are marked.
• true keeps the command, unmarked. null or false leaves it out.

Shortcuts with useHotkeyLink to "Shortcuts with useHotkey"

import { useHotkey } from "@arshad-shah/cynosure";

useHotkey("mod+s", save);
useHotkey("/", focusSearch); // plain keys are ignored while typing in a field

Shortcuts with Ctrl, Command or Alt work everywhere, text fields included. Plain keys are ignored in fields, so "/" still types a slash. Add data-cy-hotkeys="off" to a subtree (a code editor with its own bindings) to opt it out.

PropsLink to "Props"

Behaviour and accessibilityLink to "Behaviour and accessibility"

• Roles: a modal dialog named by labels.title, holding a combobox search field and a listbox of options in named groups (search results are one unnamed group). A row's group tag is part of its name. The active command is aria-activedescendant, so focus stays in the search field.
• Fresh each time: the search field is empty whenever it opens.
• Shadow DOM: works inside shadow roots (extensions), including the shortcut.

TouchLink to "Touch"

Command rows are at least 44px tall on coarse pointers. On narrow screens the panel spans the width.

ThemingLink to "Theming"

Tokens: --cy-command-palette-width, --cy-command-palette-offset (distance from the top) and --cy-command-palette-list-max-height. The backdrop uses --cy-dialog-scrim.

RelatedLink to "Related"

Menu · Combobox · Kbd · Dialog