--- title: "Command" description: "A command menu for search and quick actions: filtered as you type, driven by the keyboard, with groups, icons, shortcuts and separators, inline or in a dialog opened with ⌘K." url: "https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/command" section: "Components" --- # Command A command menu for search and quick actions: filtered as you type, driven by the keyboard, with groups, icons, shortcuts and separators, inline or in a dialog opened with ⌘K. ```html
Suggestions
Calendar
Search emoji
Calculator
Settings
Profile ⌘P
Billing ⌘B
Settings ⌘S
``` ## Markup - `.command` holds a `.command-input` (in a `.command-input-wrapper` with an icon) and a `.command-list` of `.command-item`s, optionally in `.command-group`s with a `.command-label`, split by `.command-separator`s. - `data-command` wires it up. Typing filters the items by their text, `data-value` and `data-keywords`, matching words or letters in order ("stng" finds Settings); empty groups and stray separators hide, and `[data-command-empty]` shows when nothing matches. - `↑` `↓` (wrapping), `Home` `End` and the pointer move the highlight; `Enter` activates it. The input is a combobox with `aria-activedescendant`, so screen readers follow the highlight. `aria-disabled="true"` items are skipped. - Activating an item clicks it, so a link navigates and an item with `hx-get` sends its request. It also fires `command:select` on the item, with `detail.value`. ## In a dialog Put the command in a `` and open it with a `commandfor` button. `data-command-hotkey="mod+k"` on the command opens it from anywhere on the page (`⌘`+`K` on a Mac, `Ctrl`+`K` elsewhere; the key closes it again). Each time it opens the query clears; choosing an item closes it, unless the item or the command has `data-command-keep-open`. ```html
Pages
Introduction Installation Theming
Actions
Copy link ⌘⇧C
New project ⌘⇧N

Or press Ctrl/⌘+J. (This site's search keeps K.)

``` ## Keyboard shortcuts - `data-command-hotkey` on the `.command`: opens its dialog, or focuses its input when it isn't in one. A key with no modifier (such as `/`) is ignored while typing in another field. - `data-command-hotkey` on an item: activates it while focus is in the command (`mod+shift+c` above). - Combos are keys joined with `+`: `mod` (⌘ on Apple devices, Ctrl elsewhere), `ctrl`, `meta`, `alt`, `shift` and the key. - Show a shortcut with a `.command-shortcut` at the end of the item; it is only a label. ## Scrollable The list scrolls past `max-h-72` (in a dialog, 24rem or 60% of the screen); the highlight keeps itself in view without scrolling the page. Set another `max-h-*` on `.command-list`. ```html
Ada Lovelace
Alan Turing
Barbara Liskov
Claude Shannon
Donald Knuth
Edsger Dijkstra
Frances Allen
Grace Hopper
John McCarthy
Ken Thompson
Leslie Lamport
Margaret Hamilton
Niklaus Wirth
Radia Perlman
Tim Berners-Lee
``` ## Searching on the server `data-command-filter="false"` leaves filtering to the server: an `hx-get` on the input swaps in the matching items, and the highlight follows whatever the list holds. ```html
``` ## Reference | Class | Description | | --- | --- | | `.command` | The menu: a bordered panel of an input and a list. | | `.command-input-wrapper / .command-input` | The search row and its borderless input. | | `.command-list` | The scrolling list of items and groups (max-h-72). | | `.command-group / .command-label` | A group of items and its heading. | | `.command-item` | An item (div, a or button); highlighted with data-highlighted. | | `.command-shortcut` | A shortcut label at the end of an item. | | `.command-separator` | A line between groups. | | `.command-empty` | Shown when nothing matches ([data-command-empty]). | | `.command-footer` | A row of hints under the list. | | `.command-dialog` | On a .dialog: no padding, the command fills it. | | `[data-command]` | Behaviour: filtering, keyboard, selection. | | `[data-keywords] / [data-value]` | More words to match, and the value command:select reports. | | `[data-command-hotkey]` | On the command: opens its dialog. On an item: activates it. | | `[data-command-filter="false"]` | Leave filtering to the server. | | `[data-command-keep-open]` | Don't close the dialog when an item is chosen. | | `command:select` | Event on the chosen item; detail: { value, item }. |