On this page
Overview
Show code, GoToDocument.tsx
Variants
Run a command
An item can end with its shortcut or a badge, and hints below the list say what keys do.
Show code, RunCommand.tsx
Opening it: the button and the shortcut
A secondary Button with the search icon, its label and the shortcut's keys at its far end reads like a search field.
- Pressing it opens the palette.
- So does ⌘+K on Apple platforms and Ctrl+K elsewhere, from anywhere in the window, text fields included.
Show code, InSidebar.tsx
In a narrow header
Search is an icon button named Search, with its label and keys in a Tooltip that opens below it.
Show code, IconOnly.tsx
Anatomy
Palette
Search field
Group heading
Item
Key hints
Show code, CommandPaletteAnatomy.tsx
Behaviour
Suggestions and no matches
Suggestions show until people type, such as recent items, and choose like any result.
- With none yet, an invitation says what the palette finds.
- When nothing matches, the empty state takes the list's place: it quotes what people typed and suggests checking the spelling or other words.
- Typing again brings results back.
Show code, TypeToSearch.tsx
Adapting to width
The button that opens it fills its container, such as the top of a drawer.
- Keep its label short in a narrow sidebar.
- Where even that doesn't fit, show the icon alone.
Show code, NarrowSidebar.tsx
Rules
The palette is a shortcut that shows something before people type, opened by a button labelled as a search.
Use it when
- Jumping to a document, a page or a person by name, from anywhere
- Running a command by name, such as one without a visible control
- A search button at the top of the navigation or in the top bar, with its shortcut
Show code, ShowRecent.tsx
Show code, EmptyUntilTyped.tsx
Show code, ButtonLabel.tsx
Show code, TypingLabel.tsx
One way among others
Keep another way to reach every command, such as a menu or a button: the palette is a shortcut, not the only path.
Results
Rank the best matches first, and clear the query as the palette closes.
Content
Name commands with a verb and what they act on, such as Invite people.
- Tell similar items apart with a line under the label, such as a folder.
- Show key hints only for keys the application handles.
Accessibility
| Key | Action |
|---|---|
| ⌘+K, or Ctrl+K | Opens the palette from anywhere in the window. |
| ↓, ↑ | Moves the highlight, wrapping at the ends. |
| Home, End, Page Up, Page Down | Moves to the first or last option, or by a page. |
| Enter | Chooses the highlighted option. |
| Ctrl+Enter or Cmd+Enter | Chooses it another way the application sets, such as to open beside. |
| Esc | Closes the palette and returns focus. |
Words to use
Ask for the palette's states in these words.
- Suggestions
Options shown before people type.
- Recent items
The items people opened last, before they type.
- Type to search
Inviting a search, and what it finds, with nothing to suggest.
- No results
Saying that the text found nothing, and what to try.
- With an icon
Marking an empty state, such as a search that failed.