Command

Command

A command menu: a search field over a list of items, with groups, filters and keyboard control. Stand-alone or in a dialog as a palette.

A command menu with groups, a disabled item and shortcuts

A div.command with a header holding the search field, and a role="menu" list of role="group"s of role="menuitem"s. Type to filter; the arrow keys move the highlight and Enter chooses. data-keywords adds words the search matches.

In a dialog, as a command palette

Put the command in a <dialog class="command-dialog">. A button with commandfor and command="show-modal" opens it with the field focused; choosing an item closes it, and so do Esc and a click on the backdrop (closedby="any").

Searching records, with filters

Groups with data-results show only once the field has text. The filter buttons under the header count what they would show; / lists the filters, and Backspace in the empty field removes the chosen one. data-limit caps the records and the data-more item shows more.

Tab filters, key hints and a group still loading

data-hint shows an item's keys while it is active. Tab on an item with data-tab-filter chooses that filter. A results group with aria-busy="true" shows none of its records and the menu says Searching...; remove the attribute when the records arrive. Type emma to see it.

Open it with a key

data-hotkey on the dialog.command-dialog opens it from the keyboard, and the same key closes it. Write the keys joined by +: mod is Ctrl or Cmd, then ctrl, meta, alt and shift, and last the key, such as mod+k, ctrl+shift+p or /. Separate several keys with spaces. A key with no modifier is ignored while you type in a field. Try Alt K here.

API

The command has no methods and sends no events of its own. Each item is a link or a button: listen for its click. Inside a dialog.command-dialog, choosing an item closes the dialog, except a filter item and Show more. The script starts every .command on the page, also one added later.

Keyboard

Key Description
↓ ↑ Move to the next or the previous item. A disabled or hidden item is skipped.
Enter Chooses the active item, as a click on it does.
/ Typed first in the field: lists the filters (the data-filter-list group).
Backspace In an empty field: removes the chosen filter.
Tab On an item with data-tab-filter: chooses that filter and empties the field.
Hotkey The data-hotkey of a command dialog: opens it, or closes it when it is open.
Esc In a dialog.command-dialog: closes the dialog. This is the dialog's own behaviour.

Attributes

Attribute / element Values Description
class="command" on a <div> The component: a <header> with the search <input>, an optional data-filters row and a role="menu" list.
class="command-dialog" on a <dialog> A palette: the dialog holds one .command. Choosing an item closes it, except a filter item and Show more.
role="menuitem" on an <a>, <button> or <div> An item. Listen for its click; Enter on the active item clicks it.
role="group" with a role="heading" span A group of items. It is hidden while none of its items show.
role="separator" an <hr> A line between groups. Hidden while the field has text or a filter is chosen.
data-label text on an item The name the search matches, for an item whose content is more than text. Default: the item's text.
data-keywords words on an item Extra words the search matches without showing them.
aria-disabled="true" on an item The item is skipped by the keyboard and cannot be chosen.
aria-hidden true, false Set by the script on an item the search has filtered out.
data-empty text on the menu The message when nothing matches. Default: No results found.
data-description on a span in an item Muted text after the item's name, cut with an ellipsis when long.
data-shortcut on a span in an item A shortcut at the end of the item, such as ⌘P.
data-hint on a span in an item The item's keys, as <kbd> elements and what each does. It shows while the item is active.
data-results on a group The group holds records. It shows while the field has text, or while its filter is chosen.
data-filter a key, such as orders; on a results group, a filter button or a filter item Names the filter. Choosing it shows only the results groups with the same key. The command carries the chosen key as its own data-filter.
data-filters on a div after the header The row of filter buttons. Each button's [data-count] is filled with the number of records it would show.
data-suggested on a filter button The button shows while the field is empty. Without it, a button shows only while it has a match.
data-filter-list on a group The filters listed when the field starts with /. Choosing one chooses its data-filter and empties the field.
data-filter-badge on a badge in the header Names the chosen filter in its [data-name]. Its button removes the filter.
data-limit a number on the menu The most records shown at once. Default: no limit.
data-more a number on an item Show more: choosing it shows that many more records. Its [data-count] says how many.
aria-busy="true" on a results group The group's records are on their way and none show. The menu is then aria-busy too, set by the script, and says Searching... in place of the empty message.
data-tab-filter a filter's key on an item Tab on the active item chooses that filter and empties the field.
data-hotkey keys such as mod+k, on a dialog.command-dialog Opens the dialog from the keyboard; the same keys close it. mod is Ctrl or Cmd. Several keys are separated by spaces. Default: none.
data-command-initialized true, set by the script Marks a command the script has started. Before it, items still show a hover.