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.signalaborts 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 thanhttp(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.