Command palette
<forma-command-palette>
Keyboard-first command discovery that can become a full-screen mobile surface.
- Authoring tag
<forma-command-palette>- Category
- Command and keyboard-first
- Behavior owner
- Application / Limen
- Canonical source
patterns/command-palette.html
Purpose
A command palette lets people find and run a command or jump to a record by typing, instead of hunting through menus. Forma provides the visual contract on a native dialog: a header with the title and a key hint, a search input, grouped command buttons with optional shortcuts, and unavailable commands with a stated reason. The browser owns the dialog's open state and, when opened as a modal, focus containment, Escape and focus restoration. The application or Limen owns the opening shortcut, filtering and ranking, async providers, arrow-key movement between results, running the chosen command, and never offering commands the user is not allowed to run.
Use when
- An application has many commands or destinations and frequent users want to reach them from the keyboard.
- Commands come from several providers (recent, suggested, records) and benefit from one search surface.
- The same entry point must work on phones, where it becomes a full-screen surface.
Avoid when
- A short, fixed set of actions for one object: use Action menu or Overflow command disclosure.
- Finding records in a collection with results on the page: use Search or Combobox.
- Primary navigation: use Navigation shell or Sidebar; the palette is a shortcut, not the only path.
- Terminal-style screens with fixed function keys: use Character grid keys.
Behavior to know
- Built on a native
dialog; opening modally gives focus containment, inert background, Escape to close and focus restoration for free. - Uses the heavy motion preset by default, because it is a large surface that takes over attention.
- Below 40rem wide it fills the viewport edge to edge.
- Unavailable commands stay visible as disabled buttons with a reason, instead of disappearing.
Basic example
The smallest correct markup: the canonical pattern from patterns/command-palette.html inside its public tag. Copy this first, then adapt labels, names and state.
Minimal command palette
Rendered from the canonical pattern file.
Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.
<forma-command-palette class="forma-component-tag">
<dialog class="forma-command-palette" open aria-labelledby="command-title" data-forma-motion-weight="heavy">
<header class="forma-command-palette__header">
<h3 id="command-title">Commands</h3>
<kbd>Esc</kbd>
</header>
<label class="forma-visually-hidden" for="command-search">Find a command</label>
<input id="command-search" type="search" placeholder="Type a command or record">
<div class="forma-command-palette__group">
<h4>Suggested</h4>
<button type="button"><span>Create invoice</span><kbd>⌘ I</kbd></button>
<button type="button"><span>Show items needing attention</span></button>
<button type="button" disabled><span>Publish report</span><small>Unavailable until validation passes</small></button>
</div>
</dialog>
</forma-command-palette>
Click or tap the code once to select all of it, then copy.
Examples
Opened from a toolbar button
The palette opened as a modal with a native invoker (commandfor and command="show-modal"), so the browser handles focus, Escape and returning focus to the button. A Close button gives touch users an explicit way out.
Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.
<forma-command-palette class="forma-component-tag">
<button type="button" commandfor="command-palette-toolbar-invoker-dialog" command="show-modal">Open commands</button>
<dialog class="forma-command-palette" id="command-palette-toolbar-invoker-dialog" aria-labelledby="command-palette-toolbar-invoker-title">
<header class="forma-command-palette__header">
<h3 id="command-palette-toolbar-invoker-title">Commands</h3>
<button type="button" commandfor="command-palette-toolbar-invoker-dialog" command="close">Close</button>
</header>
<label class="forma-visually-hidden" for="command-palette-toolbar-invoker-search">Find a command</label>
<input id="command-palette-toolbar-invoker-search" type="search" placeholder="Type a command or record" autocomplete="off">
<div class="forma-command-palette__group">
<h4>Recent</h4>
<button type="button"><span>Open invoice INV-1042</span></button>
<button type="button"><span>Show overdue accounts</span></button>
</div>
<div class="forma-command-palette__group">
<h4>Create</h4>
<button type="button"><span>New invoice</span><kbd>Ctrl I</kbd></button>
<button type="button"><span>New customer</span><kbd>Ctrl Shift C</kbd></button>
</div>
</dialog>
</forma-command-palette>
Click or tap the code once to select all of it, then copy.
No matching commands
The query matched nothing. The palette keeps its structure and reports the empty result in a status message the application updates, with a suggestion instead of a blank panel.
<forma-command-palette class="forma-component-tag">
<dialog class="forma-command-palette" open aria-labelledby="command-palette-no-results-title">
<header class="forma-command-palette__header">
<h3 id="command-palette-no-results-title">Commands</h3>
<kbd>Esc</kbd>
</header>
<label class="forma-visually-hidden" for="command-palette-no-results-search">Find a command</label>
<input id="command-palette-no-results-search" type="search" value="exprot ledger" autocomplete="off" aria-describedby="command-palette-no-results-status">
<div class="forma-command-palette__group">
<h4>Results</h4>
<p id="command-palette-no-results-status" role="status">No commands match "exprot ledger". Check the spelling or search for a record number.</p>
</div>
</dialog>
</forma-command-palette>
Click or tap the code once to select all of it, then copy.
Mobile
Each mobile example renders in its own document inside a real narrow viewport, so Forma's media and container queries run exactly as they would on a phone. Choose a width to compare.
Full-screen palette on a phone
At phone width the palette fills the viewport without a border. Long command names wrap and shortcut hints stay at the inline end.
Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.
What changes at narrow widths
- Below 40rem the dialog becomes 100vw by 100dvh with no border, so the on-screen keyboard and the results share the full screen.
- Command buttons are full width, so each row is a large touch target; long names wrap inside the button.
- Keyboard shortcut hints are irrelevant on most phones; keep them short or omit them so names have room.
- Uses
dvh, so the surface follows the visible viewport when browser toolbars show or hide in either orientation.
<forma-command-palette class="forma-component-tag">
<dialog class="forma-command-palette" open aria-labelledby="command-palette-mobile-full-screen-title">
<header class="forma-command-palette__header">
<h3 id="command-palette-mobile-full-screen-title">Go to</h3>
<kbd>Esc</kbd>
</header>
<label class="forma-visually-hidden" for="command-palette-mobile-full-screen-search">Find a page or record</label>
<input id="command-palette-mobile-full-screen-search" type="search" placeholder="Search pages and records" autocomplete="off">
<div class="forma-command-palette__group">
<h4>Suggested</h4>
<button type="button"><span>Items needing attention in the Northern Europe distribution region</span></button>
<button type="button"><span>Open invoice INV-1042</span></button>
<button type="button"><span>Account settings</span></button>
</div>
</dialog>
</forma-command-palette>
Click or tap the code once to select all of it, then copy.
Mobile · 320px
The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.
Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.
API and configuration
Forma components have no JavaScript API. Their public contract is the markup: native elements and attributes you write, and the CSS hooks below. The CSS hook table is generated from the built stylesheet, so it always matches the shipped implementation.
| Attribute | On | Values | Default | Description |
|---|---|---|---|---|
open | dialog | boolean | absent (closed) | Native open state. Written in markup it shows the palette non-modally, as in the canonical pattern; for real use open it modally with an invoker or showModal() so focus is contained. |
commandfor | invoker button | id of the dialog | — | Native invoker target. Pair with command. |
command | invoker button | show-modal | close | — | show-modal opens the palette as a modal; close closes it. No script needed. |
aria-labelledby | dialog | id of the header heading | — | Names the dialog after its visible title. |
aria-describedby | search input | id of the result status | — | Optionally links the result-count or empty-result message to the search field. |
type | input / button | search / button | — | Use a search input and type="button" commands so nothing submits a form by accident. |
disabled | command button | boolean | absent | Command is known but blocked now; put the reason in a small inside the button. |
role | result message | status | — | Announces result counts and empty results without moving focus. |
data-forma-motion-weight | dialog | light | standard | heavy | heavy (by CSS default) | Presentation-only mass for the entry and exit motion. See hooks. |
| Hook | Kind | Values or default | Description |
|---|---|---|---|
.forma-command-palette | Block class | — | The dialog surface: at most 42rem wide and 40rem tall with a 1rem margin from the viewport, primary surface, functional border. |
.forma-command-palette__group | Element class | — | A padded group of commands with an h4 heading. Buttons inside are full-width rows with the label at the start and a shortcut at the end. |
.forma-command-palette__header | Element class | — | Flex row with the title and a key hint or Close button, separated by a subtle rule. |
[data-forma-motion-weight] | Attribute hook | "heavy", "light", "standard" | Perceived mass for opening and closing: light, standard or heavy. Without the attribute the palette uses heavy. Presentation only; never encodes importance. |
[open] | Attribute hook | — | Styles the open state: full opacity, no offset and scale 1. The closed state is transparent, 0.75rem lower and slightly smaller so opening and closing animate. |
| Keys | Result |
|---|---|
| Tab / Shift+Tab | Moves between the search input, the Close button and each enabled command button; disabled commands are skipped natively. |
| Enter / Space on a command | Activates the command button natively; the application runs the command and closes the dialog. |
| Escape | Closes the palette natively when it was opened modally and returns focus to the invoker. A non-modal open palette does not close on Escape unless the application handles it. |
| Ctrl+K, arrow keys, type-ahead | Not built in. The opening shortcut, arrow-key movement between results and filtering as you type are application or Limen behavior. |
| Event | Description |
|---|---|
input | Native event from the search field; the application filters and updates the groups and status. |
close | Native dialog event after the palette closes, for example to clear the query. |
click | Native event on a command button; the application runs the command. |
Form behavior
The palette is not a form and submits nothing. The search input and command buttons do not participate in any surrounding form when buttons use type="button".
States
| State | How it is expressed | Presentation |
|---|---|---|
| Closed | no open attribute | Not rendered; at rest the closed styles are transparent, offset 0.75rem down and scaled to 0.985. |
| Open | open attribute / showModal() | Fully opaque at its resting position. Modal opening adds the native backdrop and inert page. |
| Unavailable command | disabled on the button | Dimmed native disabled button with a visible reason; skipped by Tab. |
| No results | application-rendered status message | An empty group with a role="status" message explaining what to try. |
| Full screen | viewport narrower than 40rem | 100vw by 100dvh without a border. |
Accessibility
Forma provides
- Uses a native
dialog, so modal opening provides focus containment, inert background, Escape and focus restoration. - Keeps commands as native buttons; unavailable ones use the native
disabledstate and show their reason as text. - Hides the search label visually with Visually hidden while keeping it as the input's accessible name.
- Honors reduced motion by collapsing transition durations to 0.01ms.
Your application supplies
- Open the palette modally (invoker
command="show-modal"orshowModal()) in real use, and provide a visible way to open it besides the shortcut. - Implement filtering, ranking, arrow-key movement and running commands; if you use an ARIA combobox/listbox pattern, implement it completely.
- Never render commands the user is not authorized to run; show blocked-but-allowed commands disabled with a reason.
- Announce result counts and empty results in a
role="status"region that exists before it changes. - Only show shortcut hints for shortcuts the application actually installs.
Responsive behavior
- Inline size is
min(42rem, 100vw − 2rem)and block size at mostmin(40rem, 100dvh − 2rem), centered withmargin: auto. - Below 40rem the palette becomes a full-screen surface: 100vw by 100dvh and no border.
- Command rows are full width; labels wrap and shortcuts stay at the inline end.
- Long result lists are the application's to page or virtualize; keep groups short.
Motion
- Opening fades in (perceptual duration) while the surface rises 0.75rem and scales from 0.985 to 1 with the inertial duration, starting from
@starting-style. - The default heavy mass makes the entry slower and more settled than a menu, matching the palette's larger attentional commitment;
data-forma-motion-weightcan lighten it. - Closing uses the same duration and easing as entry, and
displayandoverlaytransition discretely so the exit is visible before the dialog leaves the top layer. - The native open state is authoritative; interrupting mid-transition simply retargets.
- Under
prefers-reduced-motion: reducethe transition duration is 0.01ms, so the palette appears and disappears immediately.
Motion weights
Forma motion is physics-derived: perceived mass changes how a surface accelerates and settles, never what state it is in. Compare the three presentation weights of the same markup:
Usage guidance
Do
- Group results (Recent, Suggested, Create) and keep command names verb-first.
- Keep the canonical
h3title andh4group headings, which the palette's spacing rules target.
Avoid
- Making the palette the only way to reach a feature.
- Hiding blocked commands silently; users then cannot learn why an action is missing.
- Using motion weight to signal that the palette is important.
Verification specimens
Generated fault-injection specimens expose content, spacing, color-cue, and reduced-effective-contrast risks. They screen presentation robustness as engineering screens without claiming human-subject validation.