Command palette

A search field with a list of results, opened by a button or a shortcut. Jump to a page, run an action, find a record without clicking through menus. It stands on a native <dialog>, so the layer above the page, the focus trap and Esc come from the browser.

1. Try it

Open it with the button or Ctrl + K. Type “contractor” and a tag finds the page. Type “ko” and results posing as a server response arrive a moment later.

2. Markup

Items written in the HTML are filtered on the spot: without diacritics, by visible text and by the stems in data-tags. An item is a link or a button, and both look the same.

<button data-command-palette-open="#palette">Search</button>

<dialog class="command-palette" id="palette" aria-label="Search"
        data-command-palette-hotkey="k">
  <div class="command-palette-header">
    <input class="command-palette-input" placeholder="Search...">
  </div>
  <div class="command-palette-list">
    <div class="command-palette-group">
      <div class="command-palette-group-label">Pages</div>
      <a class="command-palette-item" href="/clients" data-tags="contract compan">Clients</a>
      <button class="command-palette-item" type="button" data-value="new">New order</button>
    </div>
  </div>
</dialog>

3. Classes

Class What it does
.command-palette On a <dialog>. Width: --command-palette-width (640px). Takes the whole screen on a phone.
.command-palette-header The row with an icon and the field.
.command-palette-input The field. The script gives it the combobox role and the link to the list.
.command-palette-list The scrolling list of results.
.command-palette-group A group of items. Goes away when nothing in it matches.
.command-palette-group-label The group heading.
.command-palette-item An item: <a> or <button>. data-tags holds search stems, data-value reaches the event.
.command-palette-item-label The main text of an item, cut with an ellipsis.
.command-palette-item-meta A note on the right: a tax number, a department, a shortcut.
.command-palette-footer An optional bar with key hints. Goes away on a touch screen.
.command-palette-close The close button. Created by the script and shown only on a touch screen and up to 768 px, where there is no Esc and no backdrop to tap.
.command-palette-empty The message for the empty, waiting and error states. Created by the script.
.command-palette-remote The container for server results. Created by the script.

4. Results from a server

molique has no backend, so your code sends the request. Results come through an event, not a function: the module loads asynchronously, and the listener can go in at any time, even before the module arrives.

// a result: { label, href?, meta?, group?, value? }
document.addEventListener('command:search', (e) => {
  const { query, signal, respond } = e.detail;
  respond(
    fetch('/api/search?q=' + encodeURIComponent(query), { signal })
      .then((response) => response.json())
  );
});
  • respond() takes an array or a Promise. signal aborts the request when someone keeps typing, and a late answer to an older query is ignored.
  • Everything reaches the page as text, so a record named <img onerror=...> stays a name. An address other than http(s) is dropped and the item becomes a button with no link.
  • The server checks permissions. The palette shows whatever it gets.

Choosing an item fires command:select. preventDefault() keeps the link from being followed:

document.addEventListener('command:select', (e) => {
  if (e.detail.value === 'new') {
    e.preventDefault();
    openOrderForm();
  }
});

5. Attributes and API

Attribute What it does
data-command-palette-open="#id" On any button: opens that palette.
data-command-palette-hotkey="k" On the dialog: Ctrl/Cmd + key opens and closes it. Optional, because a framework has no business claiming keys. Ignored in a contenteditable editor and over another open dialog.
data-command-palette-min="2" How many characters before asking the server.
data-command-palette-debounce="200" How many milliseconds to wait after the last character.
data-command-palette-empty="..." Your own empty-state text. The default follows the document lang (PL/EN/DE).
MoliqueCommandPalette.open(el) Opens it from code. Also .close(el). The module loads asynchronously, so call this after a click, not at page start.

6. Keyboard

Key What it does
↑ ↓ Move through the results, with wrapping.
Home, End First and last result while the field is empty. With text in the field they belong to the caret.
Enter Chooses the highlighted item.
Esc Closes and hands focus back to whatever opened the palette.

Focus stays in the field, so typing works all the time, and aria-activedescendant tells a screen reader which item is highlighted. The same handling works in Searchable Select and Multi Select.

7. Pitfalls

Tags are stems, not words.

A stem has to catch inflection: contract finds “contractor” and “contractors”.

Do not call the API at page start.

MoliqueCommandPalette may not exist yet. Use the event for results and data-command-palette-open for opening.

A new query always goes back to the top of the list.

Enter has to mean the best match, not a position left over from the previous search. Results arriving later do not disturb what the arrow keys have already reached.

8. Related pages