# Command palette

> A searchable list of commands in a dialog, opened from anywhere with a shortcut.

## Anatomy

Put a search input and a list of commands in a `<dialog class="command-palette">`. Each command is a link or button, so running one is an ordinary click. The palette picks up commands added to the list later. A command the page hides with `hidden` stays hidden. A `disabled` one is dimmed and skipped.

Start a group with an `<li class="label">`. Add an optional `.command-palette-empty` message to show when nothing matches. `AutoInit()` starts every `dialog.command-palette`. To search content instead of running commands, use [search](/search.html.md).

Open commands Ctrl+K

-   Pages
-   [Buttons](/buttons.html.md)
-   [Menu](/menu.html.md)
-   [Dialogs](/dialogs.html.md)
-   Theme
-   Dark theme
-   Light theme

No matching commands

```
<button type="button" commandfor="commands" command="show-modal">
  Commands <kbd><kbd>Ctrl</kbd>+<kbd>K</kbd></kbd>
</button>
<dialog id="commands" class="command-palette" aria-label="Commands">
  <input type="search" placeholder="Type a command" aria-label="Search commands">
  <ul>
    <li class="label">Files</li>
    <li>
      <button type="button" data-keywords="create add">
        <span class="material-symbols" aria-hidden="true">note_add</span>
        New file
        <kbd>Ctrl N</kbd>
      </button>
    </li>
    <li><a href="/settings">
      <span class="material-symbols" aria-hidden="true">settings</span>
      Settings
    </a></li>
  </ul>
  <p class="command-palette-empty" role="status">No matching commands</p>
</dialog>
```

## Keyboard

Press Ctrl+K, or Command+K on Apple platforms, to open or close the palette from anywhere on the page. The shortcut does nothing when the page has already handled the key, as an editor's own Ctrl+K does. Typing filters the commands by their text and any `data-keywords`, ignoring case and accents. Focus stays in the input. The arrow keys move the active command, and Enter runs it. Escape closes the dialog and returns focus. Each opening starts with an empty search.

Name the dialog and the input with `aria-label`. The component makes the input a combobox and the list a listbox, and reports the active command with `aria-activedescendant`.

## Options

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `shortcut` | String | `'k'` | Letter that toggles the palette with Command on Apple platforms or Ctrl elsewhere. A key event the page already handled is left alone. `null` turns it off. `data-shortcut` on the dialog sets it, and an empty `data-shortcut` turns it off. |
| `closeOnRun` | Boolean | `true` | If true, the palette closes after a command runs. |

## Methods

```
const palette = Expressive.CommandPalette.getInstance(document.getElementById('commands'));
palette.open();     // modal, with the input focused
palette.close();
palette.destroy();  // removes the shortcut, listeners, roles and ids it added
```

## Tokens

Override these on the `.command-palette`.

| Token | Default |
| --- | --- |
| `--md-comp-command-palette-max-width` | 640px |
| `--md-comp-command-palette-item-height` | 48px |
| `--md-comp-command-palette-active-container-color` | `--md-sys-color-secondary-container` |