Command | Sodium design system

Placement

When to use it

Use: The palette: every action and place in the tool, found by typing, opened with mod+k.
Use: A long list of actions on one page, filtered as the person types.
Not for: A few actions on one thing. Use Dropdown menu.
Not for: The person picks a value for a field. Use Combobox.

7 rules

Must: Give Command a label that says what it searches. Because it names the search field and the list for a screen reader, which sees neither the placeholder nor the headings while typing.
Must: Write each item as a verb and its object in sentence case; the row sets the capitals. Because an item is an action, and the matched letters are drawn from the words as written.
Should: Add keywords for the other words people use: "rerun" and "retry" for Replay. Because a keyword match ranks last but still finds the item.
Must: Set shouldFilter={false} and mount CommandLoading while results come from a server. Because the list would filter the server's answer a second time, and the pending mark says the search is still going.
Must: Keep CommandDialog's hidden title, or pass your own DialogTitle. Because the dialog is named by its title, and without one a screen reader announces only "dialog".
Never: Box CommandInput in a field or put a frame around a group. Because the search is the list's first ruled row, and a box inside the box is a second edge.
Never: Pad a CommandItem, a group heading or a shortcut in className. Because every row, the search, the headings, the items and their key caps, starts and ends on the 12px --inset, and 40px rows put each 16px icon 12px from its top and from the side, right under the search glyph.

4 states, highest first

4 checks

: The input is a combobox pointing at the active option with aria-activedescendant; focus never leaves it.
: A polite status says how many results there are, and which are unavailable.
: The active row lifts to white off the panel between two --line hairlines, text-1 on it 18.3:1 and 13:1; that lift is the focus indicator, and forced colors draw a 2px outline.
: Each option carries its place in the ranked order (aria-posinset).

4 keys

5 edge cases

Nothing matches: A sentence and the query take the list's place.
Whitespace typed: No search: every group shows as written.
Slow results: The pending mark takes the search icon's place, so the text never moves.
Touch: The key hints hide; a tap runs an item.
Phone, 390 wide: The palette leaves 16px of page each side.

8 props

Command label: string default 'Commands'
Command shouldFilter: boolean default true
Command filter: (value, search, keywords) => number default rank by match
Command loop: boolean default false
CommandDialog title, description: ReactNode | null default hidden
CommandItem value, keywords: string, string[] default its text
CommandItem onSelect: (value) => void
CommandShortcut, CommandHint keys: string

18 tokens