Every view, action and shortcut in one searchable list, opened with Ctrl K.
<main class="specimen-page" tabindex="-1">
<h1>Overview</h1>
<p><button type="button" class="cap-btn" data-cap-command-open>Commands <kbd>Ctrl K</kbd></button></p>
<p role="status" data-specimen-part="said"></p>
</main>
Installation
// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/command-menu.css";
import { enhance } from "capsomer/behavior/command-menu";
enhance();import "capsomer/tokens.css";
import "capsomer/command-menu.css";
import { CommandMenu } from "capsomer/react/command-menu";Usage
<dialog class="cap-dialog cap-cmd" data-cap="command-menu" data-placement="top" data-size="lg" aria-label="Command menu">
<div class="cap-cmd-search">
<svg viewBox="0 0 16 16" width="16" height="16" aria-hidden="true" focusable="false">…</svg>
<label class="cap-sr-only" for="cmd-input">Search commands</label>
<input class="cap-cmd-input" id="cmd-input" type="text" autocomplete="off" spellcheck="false" placeholder="Search commands"
role="combobox" aria-expanded="true" aria-controls="cmd-list" aria-autocomplete="list" aria-activedescendant="cmd-o-overview">
</div>
<div class="cap-listbox cap-cmd-list" id="cmd-list" role="listbox" aria-label="Commands" data-controlled>
<div class="cap-listbox-group" role="group" aria-labelledby="cmd-g0">
<div class="cap-listbox-label" id="cmd-g0" role="presentation">Go to</div>
<div class="cap-option" id="cmd-o-overview" role="option" data-active data-cap-command="overview" data-href="/" data-keywords="home,dashboard">
<span class="cap-option-label">Overview</span>
<span class="cap-option-keys"><span class="cap-sr-only">, shortcut </span><kbd>g</kbd> <kbd>o</kbd></span>
</div>
</div>
</div>
<p class="cap-listbox-empty" role="status" data-cap-part="empty"></p>
<div class="cap-cmd-foot" aria-hidden="true"><span><kbd>↑</kbd> <kbd>↓</kbd> move</span><span><kbd>Enter</kbd> run</span><span><kbd>Esc</kbd> close</span></div>
</dialog>
<button type="button" class="cap-btn" data-cap-command-open>Commands <kbd>Ctrl K</kbd></button><div class="cap-listbox-group" role="group" aria-labelledby="cmd-list-data-recent" data-recent>
<div class="cap-listbox-label" id="cmd-list-data-recent" role="presentation">Recent</div>
<div class="cap-option" id="cmd-o-go-media-recent" role="option" data-cap-command="go-media" data-group="Recent">…</div>
</div>
<div class="cap-option" id="cmd-o-note-field" role="option" data-cap-command="note-field" data-label="Field notes">
<span class="cap-option-label">Field notes<span class="cap-cmd-snippet">Notes from the <mark>spring</mark> survey of the north field.</span></span>
</div>
<div class="cap-listbox-group" role="group" aria-labelledby="cmd-list-data-ask-group" data-ask-group>
<div class="cap-listbox-label" id="cmd-list-data-ask-group" role="presentation">Ask</div>
<div class="cap-option" id="cmd-list-ask" role="option" data-cap-ask data-group="Ask"><span class="cap-option-label">Ask about “when is the survey”</span></div>
</div>import { createCommandMenu, stopCommand } from "capsomer/behavior/command-menu";
createCommandMenu([
{ id: "overview", label: "Overview", group: "Go to", keywords: ["home"], shortcut: "g o", run: () => go("/") },
stopCommand({ id: "pause-capsomer", label: "Pause capsomer", ask: "reason", run: () => openReasonFor("capsomer") }),
stopCommand({ id: "revoke-driver", label: "Revoke deploy-agent", ask: "preview", keywords: ["revoke"], run: () => confirmRevoke("deploy-agent") }),
{ id: "refresh", label: "Refresh now", group: "Actions", shortcut: "r", run: refresh },
]);Examples
Open, every group
<main class="specimen-page" tabindex="-1">
<h1>Overview</h1>
<p role="status" data-specimen-part="said"></p>
</main>
Filtered by what is typed
<main class="specimen-page" tabindex="-1">
<h1>Overview</h1>
<p role="status" data-specimen-part="said"></p>
</main>
Typing stop lists every stop, each saying what it asks
<main class="specimen-page" tabindex="-1">
<h1>Overview</h1>
<p role="status" data-specimen-part="said"></p>
</main>
No match
<main class="specimen-page" tabindex="-1">
<h1>Overview</h1>
<p role="status" data-specimen-part="said"></p>
</main>
An option made active with the arrow keys
<main class="specimen-page" tabindex="-1">
<h1>Overview</h1>
<p role="status" data-specimen-part="said"></p>
</main>
Comfortable density
<main class="specimen-page" tabindex="-1">
<h1>Overview</h1>
<p role="status" data-specimen-part="said"></p>
</main>
Live results: an async search answers as the person types (React)
<div data-mount="live"></div>
Mounted when idle, pages as commands, recents, a snippet and Ask (React)
<div data-mount="extras"></div>
The same extras without React: the light createCommandHost, navCommands, recentKey, a snippet and ask
<main class="specimen-page" tabindex="-1">
<h1>Home</h1>
<p><button type="button" class="cap-btn" data-cap-command-open>Search</button></p>
<p role="status" data-specimen-part="said"></p>
</main>
Live results, without React: createCommandMenu with search
<main class="specimen-page" tabindex="-1">
<h1>Home</h1>
<p role="status" data-specimen-part="said"></p>
</main>
An answer under the list (React): CommandMenu with answer, filled by an AI answer
<div data-mount="answer"></div>
An answer under the list, without React: createCommandMenu with answer, filled by an AI answer
<main class="specimen-page" tabindex="-1">
<h1>Home</h1>
<p role="status" data-specimen-part="said"></p>
</main>
API reference
CommandMenu
| Prop | Type | Required | Does |
|---|---|---|---|
open | boolean | Yes | |
onOpenChange | (open: boolean) => void | Yes | |
commands | Command[] | Yes | |
label | string | The input's accessible name (a visually hidden label). | |
placeholder | string | ||
bindKeys | boolean | Binds Ctrl K, Cmd K and "/" to open it. On by default. | |
search | (query: string, signal: AbortSignal) => Promise<Command[]> | Results from an async source as the person types (books, people, records). Called with the trimmed query and an AbortSignal, searchDelay ms (180) after the last key, never for an empty query; the signal aborts when the query changes or the menu closes. Its commands come after the matching commands, in their own groups and order, unfiltered; their ids must not repeat a command's. The last results stay until new ones arrive; a failed search keeps them. | |
searchDelay | number | ||
recentKey | string | Remember the commands run, per site, under this localStorage key, and list the last five as "Recent" while nothing is typed. | |
ask | { label?: string; run: (query: string) => void } | The way past the commands: with words typed, a last option "Ask about “…”" hands them on (to an assistant, a site search). | |
answer | AttachOptions["answer"] | An answer under the list, as the menu without React's (AttachOptions): a quiet button (label, "Answer this" when empty) while words are typed; pressing it calls run(query, region), which fills the region and returns { cancel } or a promise of it. Typing again or closing cancels it. offer: false hides the button; the app passes offer: true once its search says answers are on for the words typed (offerAnswer, in the menu without React). |
Functions
| Function | Signature | Does |
|---|---|---|
navCommands | (nav: readonly { id: string; label: string; href: string; group?: string | undefined; }[], go: (href: string) => void, group?: string): Command[] | Commands that go to each page of an app's menu ("Go to Media"), found by their group too, so the menu and the command menu never list different pages. go is the router's navigate. |
markQuery | (text: string, query: string): { text: string; mark: boolean; }[] | A text's pieces with the typed words marked, for a snippet: every case-insensitive match of a word of the query, longest words first, never overlapping. |
readRecent | (key: string): string[] | |
rememberRecent | (key: string, id: string): string[] | |
stopCommand | (o: { id: string; label: string; ask: "reason" | "preview"; keywords?: string[] | undefined; run: () => void; }): Command | A stop command: group Stop, found by "stop" and "pause", its hint saying what opening it will ask for. run must only open the control. |
groupCommands | <T extends { group: string; }>(commands: T[]): { group: string; items: T[]; }[] | Commands by group, in the order each group first appears. |
emptyText | (query: string): string | |
startAnswer | (answer: { label?: string | undefined; offer?: boolean | undefined; run: (query: string, region: HTMLElement) => AnswerRun | Promise<AnswerRun>; }, query: string, region: HTMLElement, wanted: () => boolean): Promise<...> | Starts an answer for the words typed, filling region, for the menu without React and the React menu alike. A failed load gives the words the status says (the button stays, so the person can try again). When wanted() is false once the code has loaded (the words changed or the menu closed), the answer is for nothing shown: it is canceled, the region emptied, and null returned. |
focusAnswer | (region: HTMLElement): void | Focus moves into the answer (its first focus target, or the region) before the button hides: hiding a focused button drops focus to <body>, which in a modal dialog leaves the person nowhere (WCAG 2.4.3). |
markSnippet | (el: HTMLElement, query: string): void | Fills a snippet with its text, the typed words in <mark>; built from nodes, never from HTML. |
buildMenu | (commands: Command[], opts?: MenuOptions): HTMLDialogElement | Builds the dialog's markup, exactly the contract on the doc page. |
attach | (dialog: HTMLDialogElement, run: (option: HTMLElement, found?: Command | undefined) => void, opts?: AttachOptions): Attached | Wires one menu dialog: the shared dialog's rules (Esc, the backdrop, focus handed back), the shared listbox over the commands (filtering, the active option, Enter, a click), and Ctrl K to close. run is called with the chosen option after the dialog has closed, and with its command when the option is a live result (opts.search). |
openCommandMenu | (query?: string): void | |
createCommandMenu | (commands: Command[], opts?: MenuOptions): CommandMenu | Builds a menu from a list of commands, adds it to the page, and binds Ctrl K, Cmd K and "/" to open it. |
enhance | (root?: ParentNode): () => void | Wires a menu written in markup: choosing an option follows its data-href, or dispatches a "cap-command" event (detail: { id }) on the dialog. With data-recent-key it lists recents; with data-ask, Ask follows data-ask-href with the words in q, or dispatches "cap-command" with { id: "ask", query }. Also wires every [data-cap-command-open] button under root, and binds the keys. |
matchesQuery | (c: Searchable, query: string): boolean | The listbox's own filtering, grouping and stepping, under the names this module has always exported: a case-insensitive substring over the group, the label and the keywords (so the name of a group finds all of it; an empty query matches all). |
filterCommands | <T extends Searchable>(items: readonly T[], query: string, rank?: Rank<T> | undefined): T[] | |
step | (index: number, by: number, count: number, wrap?: boolean): number |
Parts and data attributes
| Class | Is |
|---|---|
.cap-cmd | its own class |
.cap-cmd-answer | its own class |
.cap-cmd-answer-region | its own class |
.cap-cmd-answer-status | its own class |
.cap-cmd-foot | its own class |
.cap-cmd-input | its own class |
.cap-cmd-list | its own class |
.cap-cmd-search | the root |
.cap-cmd-snippet | its own class |
| State | Read from |
|---|---|
:empty | the platform |
:focus-visible | the platform |
[open] | an attribute |
Accessibility
| Key | Does |
|---|---|
Ctrl K, Cmd K, / | Opens the menu, focus in the field |
| Typing | Filters the list by group, label and keywords (typing stop lists every stop); the first match becomes active |
| Down arrow, Up arrow | Moves the active option, stopping at the ends |
| Home, End | First, last command |
| Page Down, Page Up | About a screenful |
| Enter | Runs the active command and closes the menu |
| Esc, or Ctrl K | Closes the menu; focus returns to what opened it |
- The combobox has
aria-expanded,aria-controlsandaria-activedescendant. The active option is markeddata-active, notaria-selected: nothing in a command menu is "chosen", so no option carriesaria-selected. - The active option is shown by its tint and a 3 px accent edge at its start, and by an outline in forced colors.
- The result count ("3 results") is said politely in a visually hidden
role="status"the listbox adds; "No commands match ..." is in the visiblerole="status"under the list. - The key hints under the list are
aria-hidden; this page's keyboard table and the option names carry them.