Command and keyboard-first

Command palette

<forma-command-palette>

Keyboard-first command discovery that can become a full-screen mobile surface.

Authoring tag
<forma-command-palette>
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

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.

Canonical

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.

Commands

Esc

Suggested

HTML · Minimal command palette Raw HTML for HTML · Minimal command palette
<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

Scenario

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.

Commands

Recent

Create

HTML · Opened from a toolbar button Raw HTML for HTML · Opened from a toolbar button
<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.

Scenario

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.

Commands

Esc

Results

No commands match "exprot ledger". Check the spelling or search for a record number.

HTML · No matching commands Raw HTML for HTML · No matching commands
<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.

Scenario

Unavailable commands with reasons

Commands the user may run but that are blocked right now stay listed as disabled buttons, each with a reason inside the button so it is part of the accessible name. Commands the user is not authorized to run are not rendered at all.

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.

Report actions

Esc

Publishing

HTML · Unavailable commands with reasons Raw HTML for HTML · Unavailable commands with reasons
<forma-command-palette class="forma-component-tag">
  <dialog class="forma-command-palette" open aria-labelledby="command-palette-unavailable-commands-title" data-forma-motion-weight="standard">
    <header class="forma-command-palette__header">
      <h3 id="command-palette-unavailable-commands-title">Report actions</h3>
      <kbd>Esc</kbd>
    </header>
    <label class="forma-visually-hidden" for="command-palette-unavailable-commands-search">Find a report action</label>
    <input id="command-palette-unavailable-commands-search" type="search" value="publish" autocomplete="off">
    <div class="forma-command-palette__group">
      <h4>Publishing</h4>
      <button type="button"><span>Preview report</span><kbd>Ctrl P</kbd></button>
      <button type="button" disabled><span>Publish report</span><small>Unavailable until validation passes</small></button>
      <button type="button" disabled><span>Schedule publication</span><small>Unavailable while another schedule is pending</small></button>
    </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.

Mobile example

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.

Viewport width

Frames narrower than the selected width show the component at the width available.

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.
HTML · Full-screen palette on a phone Raw HTML for HTML · Full-screen palette on a phone
<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.

Baseline

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.

Viewport width

Frames narrower than the selected width show the component at the width available.

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.

Native and ARIA attributes
AttributeOnValuesDefaultDescription
opendialogbooleanabsent (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.
commandforinvoker buttonid of the dialog—Native invoker target. Pair with command.
commandinvoker buttonshow-modal | close—show-modal opens the palette as a modal; close closes it. No script needed.
aria-labelledbydialogid of the header heading—Names the dialog after its visible title.
aria-describedbysearch inputid of the result status—Optionally links the result-count or empty-result message to the search field.
typeinput / buttonsearch / button—Use a search input and type="button" commands so nothing submits a form by accident.
disabledcommand buttonbooleanabsentCommand is known but blocked now; put the reason in a small inside the button.
roleresult messagestatus—Announces result counts and empty results without moving focus.
data-forma-motion-weightdialoglight | standard | heavyheavy (by CSS default)Presentation-only mass for the entry and exit motion. See hooks.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-command-paletteBlock 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__groupElement 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__headerElement 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.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves between the search input, the Close button and each enabled command button; disabled commands are skipped natively.
Enter / Space on a commandActivates the command button natively; the application runs the command and closes the dialog.
EscapeCloses 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-aheadNot built in. The opening shortcut, arrow-key movement between results and filtering as you type are application or Limen behavior.
Events
EventDescription
inputNative event from the search field; the application filters and updates the groups and status.
closeNative dialog event after the palette closes, for example to clear the query.
clickNative 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

Command palette states
StateHow it is expressedPresentation
Closedno open attributeNot rendered; at rest the closed styles are transparent, offset 0.75rem down and scaled to 0.985.
Openopen attribute / showModal()Fully opaque at its resting position. Modal opening adds the native backdrop and inert page.
Unavailable commanddisabled on the buttonDimmed native disabled button with a visible reason; skipped by Tab.
No resultsapplication-rendered status messageAn empty group with a role="status" message explaining what to try.
Full screenviewport narrower than 40rem100vw 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 disabled state 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" or showModal()) 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 most min(40rem, 100dvh − 2rem), centered with margin: 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-weight can lighten it.
  • Closing uses the same duration and easing as entry, and display and overlay transition 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: reduce the 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:

lightpresentation only

Commands

Esc

Suggested

standardpresentation only

Commands

Esc

Suggested

heavypresentation only

Commands

Esc

Suggested

Usage guidance

Do

  • Group results (Recent, Suggested, Create) and keep command names verb-first.
  • Keep the canonical h3 title and h4 group 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.