command-palette

Universal Cmd+K command palette with search, keyboard navigation, and grouped actions.

Description

The <command-palette> component provides a universal Cmd+K search and action launcher. It opens as a modal dialog with a search input that filters through grouped commands. Different from <site-search> (which is Pagefind site search) — this is for user-defined commands and actions.

Basic Usage

<command-palette data-hotkey="meta+k"> <command-group label="Navigation"> <command-item value="home" data-hotkey="meta+h"> Go Home </command-item> <command-item value="settings"> Settings </command-item> </command-group> <command-group label="Actions"> <command-item value="theme">Toggle Dark Mode</command-item> <command-item value="copy">Copy Current URL</command-item> </command-group> </command-palette>

Attributes

Attribute	On	Description
`data-hotkey`	`command-palette`	Global keyboard shortcut (default: `meta+k`)
`data-placeholder`	`command-palette`	Search input placeholder text
`data-discover`	`command-palette`	Auto-populate from `[data-command]` elements on the page
`label`	`command-group`	Group header text
`value`	`command-item`	Value passed in `command-palette:select` event
`data-hotkey`	`command-item`	Display keyboard shortcut badge on item

With Icons

Use slot="icon" on icon elements inside <command-item>:

<command-palette data-hotkey="meta+k"> <command-group label="Navigation"> <command-item value="home"> <icon-wc name="home" slot="icon"></icon-wc> Go Home </command-item> <command-item value="settings"> <icon-wc name="cog" slot="icon"></icon-wc> Settings </command-item> </command-group> </command-palette>

Trigger Button

You can add a visual trigger button that opens the palette:

<button onclick="document.querySelector('command-palette').open()"> Search commands... <kbd>⌘K</kbd> </button>

Auto-Discovery (`data-discover`)

Add data-discover to <command-palette> to auto-populate the palette with [data-command] elements from the page. Any button, link, or element with data-command becomes searchable. If it also has data-shortcut, the shortcut is displayed and bound as a real keyboard shortcut. Selecting a discovered command in the palette clicks the original element.

<command-palette data-hotkey="meta+k" data-discover> <command-group label="Navigation"> <command-item value="home">Go Home</command-item> </command-group>  </command-palette>  <button data-command="Toggle Dark Mode" data-shortcut="meta+shift+t"> Dark Mode </button> <a href="/docs" data-command="Documentation" data-command-group="Navigation"> Docs </a>

`data-command` Attributes

Attribute	Description
`data-command`	Label in the palette (required to opt in)
`data-command-group`	Group name (default: "Page Actions")
`data-command-icon`	Icon name for `<icon-wc>` in palette
`data-shortcut`	Keyboard shortcut — displayed AND bound globally

<button data-command="Save Draft" data-shortcut="meta+s" data-command-icon="save"> Save </button>

Elements with commandfor (HTML Invoker API) are also auto-discovered. The label comes from textContent; override with data-command if needed.

Aggressive Auto-Discovery (`data-discover="auto"`)

Set data-discover="auto" to also scan for nav links and page headings without any explicit data-command attributes:

Source	Palette label	Group
`nav a[href]` links	Link text	"Navigation"
Headings with `id` (`h2[id], h3[id]`)	"Jump to: { heading text }"	"On This Page"
`[data-command]` elements	`data-command` value	`data-command-group` or "Page Actions"

<command-palette data-hotkey="meta+k" data-discover="auto"> <command-group label="Quick Actions"> <command-item value="theme">Toggle Dark Mode</command-item> </command-group> </command-palette>

Auto-discovered items are capped at 50 and styled with muted text. Elements inside footer, aside, dialog, [hidden], or [aria-hidden="true"] are excluded. Clicking a heading command scrolls to it smoothly.

Keyboard Navigation

Key	Action
`Cmd+K` / `Ctrl+K`	Open/close palette
`Arrow Down`	Move to next item
`Arrow Up`	Move to previous item
`Enter`	Select active item
`Escape`	Close palette

JavaScript API

Methods

Method	Description
`open()`	Open the command palette
`close()`	Close the command palette

Events

Event	Description
`command-palette:select`	Fired when an item is selected (`detail.value`)
`command-palette:open`	Fired when palette opens
`command-palette:close`	Fired when palette closes

const palette = document.querySelector('command-palette'); // Open programmatically palette.open(); // Listen for selection palette.addEventListener('command-palette:select', (e) => { console.log('Selected:', e.detail.value); switch (e.detail.value) { case 'theme': document.documentElement.toggleAttribute('data-dark'); break; case 'home': window.location.href = '/'; break; } });

Accessibility

Opens as native <dialog> with focus trapping
Search input focused on open
Full keyboard navigation (Arrow keys, Enter, Escape)
Items have role="option" within a role="listbox"
Active item scrolls into view
Platform-aware keyboard shortcut display (⌘ on Mac, Ctrl on others)