Prepared Docs

Overview

Command is a keyboard-first palette for search and action. It pairs an input with a scrollable, grouped result list and runs whatever command the operator picks: open an incident, change status, jump to a module, trigger a supervisor tool. Dispatch uses the family for incident search, email-template selection, filter pickers, and fast navigation. The mental model is "OS-level command launcher inside the product": type what you want, pick from a ranked list, act. A command palette earns its weight when operators can't remember the exact menu path but know the name of the thing; it's the wrong shape for static form pickers or narrow-scope selection.

When to use

For global or contextual shortcuts

Jump to an incident by id, open a supervisor tool by name, change shift status. Palette-first surfaces pay off when the total set of actions is large but the user knows a keyword.

"Open recent incident", "Start a new QA review", "Jump to agency settings"—commands and navigations live next to each other, grouped by heading. This is where command beats a menu: the result list is ranked by relevance, not hard-coded by IA.

For keyboard-first workflows on desktop-class viewports

Operators who know the shortcut (Cmd/Ctrl+K) move faster than a mouse-first equivalent. A palette is the affordance that makes the shortcut worth remembering.

When not to use

For small, static pickers

Use Menu or Combobox. When the list is a handful of options, a palette is overkill and adds a close/open ceremony for no speed gain.

For mobile-primary flows without a hardware keyboard

Provide visible navigation and touch-sized controls. A command palette on mobile is rarely faster than a directly placed button.

For destructive actions that need confirmation

Palette selection should not commit to a destructive operation. Route through an explicit Modal step after selection so the confirmation has weight.

For returning a value into a form

Use Combobox. A palette runs an action; a combobox produces a selected value.

Variants

Aspect	Purpose	Emphasis
Input	Typeahead that filters the list	Placeholder describes the action ("Search incidents...")
Groups	Categorize results (Recent, Actions, Navigation)	Short, sentence-case headings; group only when it helps scanning
Loading row	Signals async work	Keep it non-blocking—do not freeze the input while results resolve
Empty row	Communicates no matches	Actionable copy ("No matches for 'foo'. Try another term.")
Footer hints	Show keyboard shortcuts for power users	Display-only; do not hard-code user keymaps that vary by product

Composition

The palette is typically mounted inside a Modal shell: header with the input, scrollable body of grouped items, optional footer with hints. CommandItems render a primary label, optional subtitle, and optional trailing metadata (icon, shortcut, status dot). Keep items visually consistent so scanning top-to-bottom doesn't require re-parsing each row.

Grouping

Use groups when the items belong to different mental buckets ("Recent", "Actions", "People"). Skip grouping when there's only one bucket—a single heading adds chrome without adding scent.

Async results

When results come from the server, set shouldFilter={false} on the Command wrapper so cmdk doesn't re-filter pre-filtered data. Debounce the query, surface a loading row while in flight, and show an actionable empty state when the response is zero-length.

Content guidelines

Input placeholder. Describes the action, not the UI ("Search incidents or jump to a page", not "Type to search").
Item labels. Noun-first for scanning ("Incidents—Recent", "Agencies—Settings"). Localize with formatMessage.
Subtitles. Context that disambiguates similar items (an id, an agency, a timestamp), not redundant category text.
Empty states. Suggest the next move ("Try another term" or "Nothing scheduled for today").
Keyboard hints. Use consistent glyphs (⌘K, ↵, Esc). If keymaps vary by product, read them from the source of truth rather than hard-coding.

Behavior and states

Open/close. A shortcut and a visible button both open the palette. Close on selection, Escape, or explicit dismiss. Return focus to the opener on close.
Async. Debounce requests; cancel in-flight requests on input change; keep the input responsive even while results resolve.
Server-filtered results. Set shouldFilter={false} so cmdk does not hide rows the server already matched.
Recent and pinned items. Preserve them across sessions when product requirements allow. A palette that forgets what you just did punishes muscle memory.
Loading and empty. Neither should block the input. Operators retype when the first query was wrong; a frozen input makes that worse.

Best practices

Group focused, short lists. Long unlabelled columns defeat the purpose of a palette.
Rank by recency, frequency, and string match—not alphabetical. A palette is a ranked launcher, not a directory.
Show visible affordances (button, hint, tooltip) for the open shortcut; undiscoverable palettes are invisible palettes.
Duplicate critical actions in a visible surface (menu, button) so the palette is a shortcut, not the only path.

Don't

Fetch unbounded lists without pagination or ranking. Cap and sort results.
Render a palette for a list of three options; that's a menu's job.
Auto-commit on Enter if the focused row is destructive. Route destructive verbs through a confirmation step.
Trap focus so tightly that Escape stops working or Tab loops without returning to the input.

Accessibility

cmdk manages listbox semantics, highlight state, and keyboard navigation inside the palette. The app supplies the dialog's accessible name, the input's label, the live-region strategy for result counts, and the focus restoration on close. See Accessibility for the full contract including focus trap, labelling, and announcement patterns.

Combobox for form-embedded typeahead that returns a value.
Menu for button-attached static action lists.
Modal for the dialog shell that hosts the palette.
Button for the visible trigger affordance.

Combobox / Accessibility

Command / API and Development

Overview

When to use

For global or contextual shortcuts

For typeahead that mixes actions and navigation

For keyboard-first workflows on desktop-class viewports

When not to use

For small, static pickers

For mobile-primary flows without a hardware keyboard

For destructive actions that need confirmation

For returning a value into a form

Overview

When to use

For global or contextual shortcuts

Jump to an incident by id, open a supervisor tool by name, change shift status. Palette-first surfaces pay off when the total set of actions is large but the user knows a keyword.

For keyboard-first workflows on desktop-class viewports

Operators who know the shortcut (Cmd/Ctrl+K) move faster than a mouse-first equivalent. A palette is the affordance that makes the shortcut worth remembering.

When not to use

For small, static pickers

Use Menu or Combobox. When the list is a handful of options, a palette is overkill and adds a close/open ceremony for no speed gain.

For mobile-primary flows without a hardware keyboard

Provide visible navigation and touch-sized controls. A command palette on mobile is rarely faster than a directly placed button.

For destructive actions that need confirmation

Palette selection should not commit to a destructive operation. Route through an explicit Modal step after selection so the confirmation has weight.

For returning a value into a form

Use Combobox. A palette runs an action; a combobox produces a selected value.

Variants

Aspect	Purpose	Emphasis
Input	Typeahead that filters the list	Placeholder describes the action ("Search incidents...")
Groups	Categorize results (Recent, Actions, Navigation)	Short, sentence-case headings; group only when it helps scanning
Loading row	Signals async work	Keep it non-blocking—do not freeze the input while results resolve
Empty row	Communicates no matches	Actionable copy ("No matches for 'foo'. Try another term.")
Footer hints	Show keyboard shortcuts for power users	Display-only; do not hard-code user keymaps that vary by product

Composition

Grouping

Use groups when the items belong to different mental buckets ("Recent", "Actions", "People"). Skip grouping when there's only one bucket—a single heading adds chrome without adding scent.

Async results

Content guidelines

Input placeholder. Describes the action, not the UI ("Search incidents or jump to a page", not "Type to search").
Item labels. Noun-first for scanning ("Incidents—Recent", "Agencies—Settings"). Localize with formatMessage.
Subtitles. Context that disambiguates similar items (an id, an agency, a timestamp), not redundant category text.
Empty states. Suggest the next move ("Try another term" or "Nothing scheduled for today").
Keyboard hints. Use consistent glyphs (⌘K, ↵, Esc). If keymaps vary by product, read them from the source of truth rather than hard-coding.

Behavior and states

Open/close. A shortcut and a visible button both open the palette. Close on selection, Escape, or explicit dismiss. Return focus to the opener on close.
Async. Debounce requests; cancel in-flight requests on input change; keep the input responsive even while results resolve.
Server-filtered results. Set shouldFilter={false} so cmdk does not hide rows the server already matched.
Recent and pinned items. Preserve them across sessions when product requirements allow. A palette that forgets what you just did punishes muscle memory.
Loading and empty. Neither should block the input. Operators retype when the first query was wrong; a frozen input makes that worse.

Best practices

Group focused, short lists. Long unlabelled columns defeat the purpose of a palette.
Rank by recency, frequency, and string match—not alphabetical. A palette is a ranked launcher, not a directory.
Show visible affordances (button, hint, tooltip) for the open shortcut; undiscoverable palettes are invisible palettes.
Duplicate critical actions in a visible surface (menu, button) so the palette is a shortcut, not the only path.

Don't

Fetch unbounded lists without pagination or ranking. Cap and sort results.
Render a palette for a list of three options; that's a menu's job.
Auto-commit on Enter if the focused row is destructive. Route destructive verbs through a confirmation step.
Trap focus so tightly that Escape stops working or Tab loops without returning to the input.