CommandMenu

Usage

This section includes guidelines for designers and developers about the usage of this component in different contexts.

Content guidelines

Command titles should be clear, accurate and predictable. It should be possible for the user to understand what will happen when they execute a command:

Always lead with a strong verb that encourages action. To provide enough context to user, use the {verb} + {noun} content formula:

When writing command titles, always write them in sentence case, not title case. The first word should be capitalized and the rest lowercase (unless a proper noun):

Avoid unnecessary words and articles in command titles, such as “the”, “an” or “a”:

Avoid ending in punctuation:

Use ellipsis in the title when describing sections that have commands grouped inside of them:

Commands data

Each command in the commands data array must include at least an id and title. A command may also include properties for section, icon, handler, shortcut, forceShortcut, parent, and keywords:

Defining shortcuts

Shortcuts in the Command Menu have the following form: [modifier]+[key]. Shortcuts are made up of a sequence of presses. A press can be as simple as a single key which matches against KeyboardEvent.code:

// Matches: event.code:
'KeyD'

Presses can optionally be prefixed with modifiers which match against any valid value to KeyboardEvent.getModifierState().

'Control+KeyD'
'Meta+KeyD'
'Shift+KeyD'
'Alt+KeyD'
'Meta+Shift+KeyD'

There is also a special $mod modifier that makes it easy to support cross platform keybindings:

• Mac: $mod = Meta (⌘)
• Windows/Linux: $mod = Control

'$mod+KeyD' // ⌘/Ctrl + D
'$mod+Shift+KeyD' // ⌘/Ctrl + Shift + D

The Command Menu itself can be opened using ⌘+k (or Ctrl+k on Windows) and closed by hitting Esc. These are both non-configurable shortcuts in order to unify the experience across our platforms.

Choosing shortcuts

When choosing shortcuts, it is very important that they do not clash with native operating system or browser shortcuts.

For example, you should not define a shortcut like $mod+KeyC, since this will clash with the native “Copy” shortcut, and will be triggered every time a user copies text in the app. Nor should you use shortcuts like Shift+KeyA since this will get triggered whenever a user types an uppercase “A” character. Therefore, special care and attention must be given to each and every shortcut choice.

In general, we recommend using the Alt modifier, since this is less likely to clash with existing shortcuts. However, be aware, the Alt key is also used for accented characters e.g. Alt+KeyA produces the letter “å”. Again, it is crucial that you choose shortcuts carefully.

Browser-reserved shortcuts

Some key combinations are reserved by the browser or operating system and are unsafe to use as a command shortcut. By default a command's handler runs but the browser's own action runs too, so a reserved combo (for example Alt+KeyD) will still focus the address bar. Avoid the following:

If you knowingly want a command to take over a reclaimable reserved combo, set forceShortcut: true on that command — the Command Menu then calls event.preventDefault() so the browser default does not run:

({
  id: 'dashboard',
  title: 'Go to dashboard',
  shortcut: 'Alt+KeyD',
  forceShortcut: true, // opt in to reclaim Alt+D from the browser
  handler: () => {
    // navigate to the dashboard
  },
})

This is opt-in so command shortcuts never silently override browser or OS keys. Even so, reusing a reserved combo will surprise users who expect the address bar, so prefer a different combination where you can. Alt+Home and Alt+F4 are intercepted before the page receives the event and cannot be reclaimed even with forceShortcut.

You should strive to choose shortcuts that are intuitive and easy to remember. The more complex a shortcut, the less likely a user is to remember it. Of course, a user can still find a command by searching the command menu, and for some users this may be their preferred way of triggering commands.

Common keybindings

Keybindings will be matched against KeyboardEvent.key and KeyboardEvent.code which may have some names you don’t expect. Please note that we recommend always using KeyboardEvent.code for defining the keys and only using KeyboardEvent.key for defining modifiers.

In addition to the above table, you can use https://keycode.info/ for checking the specific values needed. Note that some keys will have the same code as others because they appear on the same key on the keyboard. Keep in mind how this is affected by international keyboards which may have different layouts.

Navigating with the command menu

1. Use Ctrl+K (Windows/Linux) or Cmd+K (Mac) to open the command menu.
2. Start typing the command you want to execute. The suggestions in the command menu change to match your text.
3. Finish entering the name, or use the arrow keys to highlight the command you want from the list of suggestions.
4. Use Enter to execute the chosen command.
5. If you chose a command that has nested commands, you can use Backspace to return to the previous menu.
6. When the command menu is active, you can use one of the following keyboard shortcuts to close it: Esc, Ctrl+K (Windows and Linux) or Cmd+K (Mac).