Command Palette

Demo & usage

More examples

When to use

• Giving power users a fast keyboard launcher for actions and navigation.
• Apps with many commands where menus would be unwieldy.
• Remote/async command sources — drive `[loading]` from `queryChange`.
• For searching data records specifically, use the Search Bar.

Async states

• loading
• error
• retry

Item identity & owned state

Restorable state

• recentCommandIds

Bind these to put a saved view back — the open sections, the hidden columns, the selected rows — and read their Change events to store what the user does.

Outputs

Wire it to your API

This component is headless about transport: it renders what you give it and reports what the user asks for. Nothing below requires @styloviz/data — it just saves you writing the debounce, the request guard and the retry policy by hand.

• `queryChange` carries an `SvDataQuery` — page, page size, sorts, filters, search and cursor in one object. One handler covers every way the user can change what they are asking for.
• `serverSide` switches **off** the built-in filtering, sorting and paging. Leave it false and the component works entirely from the array you pass — which is what you want for a few hundred rows.
• `debounceMs` (default 300) collapses a burst of typing into one request. Set it to 0 only when the query is driven by clicks.
• Normalize failures with `toSvDataError()` from `@styloviz/core`. It derives `retryable` from the status, so a 404 does not get a "Try again" button that can only fail again.

Full walkthrough: Connecting to a backend.

Customization & theming

• Light/dark theme variants, three sizes (sm · md · lg), and top/center placement.
• Grouped, searchable commands with substring or fuzzy (subsequence, ranked) matching; recent history and badges.
• Configurable/optional global shortcut, `showRecent` toggle, disabled and keep-open commands.
• The open shortcut goes through the shared registry (`X-15`): `config.shortcutScope` puts it in the global, route or overlay band — the listener used to be bound unconditionally to `document`, so a palette inside a dialog competed with the app's own on equal terms — and a second component claiming the same binding is refused and reported rather than firing alongside it.
• A command's `keys` (e.g. `'mod+shift+p'`) is a real binding: it renders itself for the running platform, colliding ones are reported through `(shortcutConflicts)`, and `config.bindCommandKeys` registers them so pressing one runs the command through the same path a click takes. `shortcut` remains the display-only glyph array.
• Rendered into `document.body` via a portal, so it always covers the full viewport and is never clipped by a parent `overflow`/`transform`.
• Return a `Promise` from a command `action` for an inline loading spinner; remote sources use `[loading]` + `queryChange`; failures keep the palette open with an error state and emit `commandError`.

Best practices

• Do: Register the ⌘K/Ctrl+K shortcut and hint it in the UI (customise with `config.shortcutKey`).
• Do: Group commands and surface recents so frequent actions are one keystroke away.
• Do: Enable `config.fuzzy` for forgiving, ranked matching on large command sets.
• Tip: Keep command labels verb-first ("Create invoice") for scannability.
• Do: Give a command `keys` rather than a `shortcut` glyph array. `keys` is a binding: it renders itself as ⌘⇧P or Ctrl Shift P for the platform the user is on, and two commands claiming the same one are reported through `(shortcutConflicts)`. The glyph array binds nothing and cannot be checked against anything.
• Do: Set `config.shortcutScope` to `'overlay'` for a palette that lives inside a dialog, so its ⌘K outranks the app's while the dialog is open and hands it back on close.
• Tip: Turn on `config.bindCommandKeys` only if the app does not already bind its commands itself — otherwise every shortcut fires twice.
• Don't: Don't use a key the browser keeps for itself — ⌘/Ctrl + N, T, W, Q, Tab, or Shift + N/T/W — as the open key or a command key. The page never receives it in a browser tab; the palette warns about it in dev mode.

Accessibility

• Combobox semantics with `aria-activedescendant` on the search input tracking the active result; `role="listbox"`/`option` results with `aria-selected` and `aria-disabled`.
• Full keyboard control (↑↓ skip disabled, Enter, Esc, Tab); focus returns to the prior element on close — and if a command removes that element (a navigation tearing down the old view), focus moves to a surviving neighbour or the main landmark once the exit transition ends, instead of `<body>`. Opened with nothing focused, it hands focus to the main landmark.
• With `resultsFor`, rows that answer an older term — including during the debounce window, before the new term has been requested — stay on screen dimmed but `inert`, are dropped from `aria-activedescendant`, and cannot be run.
• Running commands set `aria-busy`; async failures are announced via an assertive live region.