Geist Design System

Command Menu

Launch a set of actions as a full-screen overlay.

Default

Best Practices

When to use

  • Use CommandMenu for a global, keyboard-first command palette that finds resources and runs actions across the app.
  • For a menu opened from a visible trigger on a single resource, use Menu; for right-click on a row, use ContextMenu.
  • Group items into pages (Projects, Team Settings) when a single flat list would exceed roughly 30 items or span multiple resource types.

Behavior

  • Bind ⌘K on macOS and Ctrl+K elsewhere. Don’t reuse the binding for any in-page filter input; it’s a global shortcut.
  • Open into the root page; preserve the search query when navigating back from a sub-page so the user’s typing isn’t lost.
  • Trap focus inside the overlay while it’s open and return focus to the previously active element on close.
  • Show a recent or default item set when the input is empty so the menu is useful before typing.

Content

  • <CommandMenu.Item> children are Title Case verb phrases (Deploy Project, Invite Team Member). Avoid navigation phrasing like Go to project page; CommandMenu commands act, not browse.
  • CommandMenuPage.label is Title Case and names the scope (Projects, Team Settings).
  • CommandMenuPage.placeholder is sentence case, action-oriented, and ends with … (Search projects…, Type a command or search…). Bare Search… is wrong because it doesn’t name the scope.
  • <CommandMenu.Group heading> is Title Case, 1–2 words (Actions, Recent).

Accessibility

  • Use aria-live="polite" on the result count so screen readers hear how the list narrows as the user types.
  • Up/Down arrows move highlight, Enter activates, Escape closes. Backspace at an empty input pops the page stack.
  • Display each item’s keybind as a Kbd slot so the shortcut is discoverable to sighted users and announced as a label to screen readers.