Command palette

The ⌘K palette: navigation, commands and live catalogue search.

Guidance

The command palette is the keyboard entry point to everything in the catalog. It mixes page navigation and actions (commands, filtered locally with a prefix, then word-start, then substring scorer that also matches keyword synonyms) with live catalogue results (search, debounced 120ms, stale calls aborted). It opens and closes instantly: the guidelines bans animated command palettes, so the dialog has no transition at all.

Scope the search with Tab (All, Assets, Glossary, Teams, Pages) or the chips under the input, and type > to see commands only. With an empty query it shows recents, then every command.

Every row shows its own shortcut as a keycap when it has one, and the active row also shows the Enter keycap, so the key that will act is always on screen. Rows without a shortcut show only the Enter keycap when active.

Built as a modal <dialog> containing an ARIA combobox (the input, with aria-activedescendant) that controls a grouped listbox, following https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-autocomplete-list/. Keys: ArrowDown and ArrowUp move and wrap, Home and End jump to the first and last result, PageDown and PageUp move by ten, Enter opens the active row, Tab and Shift+Tab change scope, Escape closes and returns focus to where it was. Set global-shortcut to toggle with ⌘K or Ctrl+K anywhere.

Selecting a row fires mm-select; unless that is cancelled, the palette then calls the command's run() or navigates to its href. It always closes.

With search-href (such as /discover?q={query}), every typed query ends with a "Search the catalog for …" row that opens the full search page, so people can always get from the palette to every result, including when nothing matched. It fires mm-search-all; cancel it to route in a single-page app.

Properties

Property	Attribute	Type	Default	Description
open	open	boolean	false	Opens the palette as a modal dialog.
inline	inline	boolean	false	Renders the panel in place instead of as a modal, for documentation and embedded launchers.
commands		PaletteCommand[]	[]	Static navigation and actions, filtered locally. Filter by permission before passing them in.
recents		PaletteItem[]	[]	Shown above the commands when the query is empty.
search		PaletteSearch | undefined		Live catalogue search. Called 120ms after typing stops; the signal aborts when a newer query starts.
query	query	string	''	The search text, without the > prefix.
scope	scope	PaletteScope	'all'	all (default), assets, glossary, teams, pages or commands (the > prefix).
placeholder	placeholder	string	''
searchHref	search-href	string	''	The full search page, with {query} where the encoded query goes, e.g. /discover?q={query}. Adds a "Search the catalog for …" row to every query.
globalShortcut	global-shortcut	boolean	false	Toggle with ⌘K on Apple platforms and Ctrl+K elsewhere, from anywhere on the page.
slashShortcut	slash-shortcut	boolean	false	Also open with "/" when focus is not in a text field.

Methods

Method	Description
show()	Opens the palette and focuses the input.
hide()	Closes the palette and returns focus to where it was.

Events

Event	Detail	Description
mm-select	CustomEvent<MmPaletteSelectDetail>	When a row is chosen. Cancel it to handle href or run yourself.
mm-open	CustomEvent<null>	When the palette opens.
mm-close	CustomEvent<null>	When the palette closes.
mm-query	CustomEvent<MmPaletteQueryDetail>	When the query or scope changes.
mm-search-all	CustomEvent<MmPaletteSearchAllDetail>	When "Search the catalog for …" is chosen. Cancel it to route yourself.

CSS parts

Part	Description
panel	The dialog panel (mm-raised, radius-lg, shadow-dialog).
input	The native input (role combobox).
scopes	The scope chip row.
listbox	The scrolling listbox.
option	Each option row.
footer	The navigation hints on mm-sunken.

Examples

Every state of mm-command-palette in Storybook, with keyboard and screen reader tests.