Home
Previous componentNext component

Command menu

Open in fibo's Storybook

A Cmd+K palette for moving around an app and running actions. Commands can open pages of their own, the ones you ran last come first, a search ranks every command across every page, and a side pane previews the highlighted one.

Command menuClick the field, or press Cmd+K or Ctrl+K anywhere on this page.

Anatomy

The dialog is three regions stacked over a backdrop: the search field, the list of commands with an optional preview pane beside it, and the keyboard hints.

The dialogMid-search, so every region is on screen.

Each row carries a label and, when it has them, an icon, where it lives, a shortcut and a chevron for a page.

A rowOne of each kind: highlighted, with a shortcut, opening a page, and disabled.

Variants and states

Views

The menu has three views, and a few states within them.

HomeRecent commands first, then your groups in order.
Search resultsOne ranked list across every page, each row naming where it lives.
Page openA back button, a breadcrumb and the page's own hint.
No matchesA search with no results says so.
Without hintsFor apps where people already know the keys.

With a preview

When anything on screen has a preview, the dialog widens and a pane follows the highlight. Commands without one show No preview. On small screens the pane hides.

Preview paneFiles show a thumbnail and an excerpt, people their role.

Rows

Each row can carry an icon, a shortcut and a chevron for a page. Recent commands and search results also name where they live, and a disabled row fades.

Row statesHighlighted with context, a shortcut, a page, and disabled.

Usage

  • 01Use it for moving around an app and running actions people would otherwise hunt for in menus.
  • 02Put the commands people use most in the first group, and keep groups to a handful each.
  • 03Make a command a page when it needs a choice before it can run: a theme, a person, a status. Keep pages one or two levels deep.
  • 04Add the words people might type instead: appearance for Change theme, create for New file.
  • 05Don't make it the only way to reach something. It speeds up people who know it's there.

In a header

The usual home: a search field in the app's header, where people look for search.

AcmeProjectsDocs
Click the field in the header.

Your own trigger

Any button can open it in place of the search field.

A ghost button labelled Commands.

Opened from anywhere

With no trigger, the app decides when it opens, from a button, a menu item or the shortcut.

Last command: none

Open it, run a command, and the page shows which.

Best practices

DoGroup the choices for one action on a page of their own.
Don'tDon't list every variant on the first page. It buries the other commands.
DoStart actions with a verb and name places plainly, so the list scans.
Don'tDon't write sentences or mix styles. People read the list as they type.
DoGive previews to things people choose between by content: files, people, records.
Don'tDon't preview plain actions. The pane widens the dialog and mostly says No preview.

Accessibility

Everything works from the keyboard, and the keys are the ones people know from other palettes.

KeyDoes
⌘K or CtrlKDoesOpens and closes the menu from anywhere on the page
↑↓DoesMoves the highlight
↵DoesRuns the highlighted command, or opens its page
⌫DoesOn an empty search, steps back out of a page
EscDoesClears the search, then leaves the page, then closes
  • 01It's a modal dialog named Command menu. Focus goes to the search field when it opens, stays inside while it's open, and returns to the trigger when it closes.
  • 02A screen reader reads each command as the highlight moves, says which group it's in, and says when a command opens a page.
  • 03On a page, the search field is named after it, and the back button says where it goes.
  • 04A search announces how many results it found, and the preview pane is announced as it changes.
  • 05Every piece of text the menu writes can be translated.

References