Command

When to use

• As a command palette for coaches who know what they want: type "add" and press Enter to add a client, or type a client's name and jump to their profile. In coach-admin it opens with ⌘K (Ctrl+K on Windows).
• For a searchable list of actions and records in one place: "Add client", "Create program", "Review check-ins", then matching clients.
• Inside a popover, as the list part of a Combobox.

This site's own search (⌘K in the header) is built on the same cmdk library.

When not to use

• As the only way to reach something. Every command also exists as a button, link or menu item; the palette is a shortcut.
• To pick one value in a form from a short list: use a Select. For a long list, use a Combobox, which is built from Command.
• For actions on one item (a client row): use a dropdown menu.
• For the main navigation: use the Sidebar.

Anatomy

Not shown: the empty message, which replaces the list when nothing matches ("No actions or clients match."), and separators between groups.

Variants

CommandDialog takes open and onOpenChange, plus a title and description for screen readers (visually hidden). Always pass them in the screen's language: the defaults are English ("Command Palette").

In coach-admin, open it from a button in the header and with ⌘K / Ctrl+K, registered once at the app level. This preview opens it from a button only, because ⌘K on this site opens the site search.

States

Type a name that isn't in the first preview, such as "Noura", to see the empty state.

Usage guidelines

• Put actions first, then records (clients, programs), each in its own group.
• Show a few useful suggestions before the coach types: the most used actions and recent clients.
• Run the command on Enter and close the dialog. If the action opens something, focus moves there.
• Shortcuts in items are hints for the same action elsewhere. Only show shortcuts that really exist.

Content guidelines

• Actions start with a verb, like buttons: "Add client", "Create program". Records use their name: "Sara Al-Harbi".
• The placeholder says what can be found: "Search actions and clients…". Not just "Search…".
• Group headings are plural nouns: "Actions", "Clients", "Programs".
• The empty message says what didn't match, without blame: "No actions or clients match."
• Arabic: actions use the verbal noun, like buttons: "إضافة عميل"، "إنشاء برنامج".

Accessibility

• The input is a combobox that controls a listbox; items are options, and the highlight is aria-activedescendant, so focus never leaves the input. Moving the highlight reads "Create program, 2 of 3".
• Label the input with label on Command (a visually hidden label). CommandList is named "Suggestions" from the UI labels, in Arabic on Arabic screens.
• CommandDialog passes its title to its Command as the label, and renders the title inside the dialog, so both the dialog and the input are named ("Command palette" by default, from the UI labels). Upstream rendered the title outside the dialog and left the input unlabelled.
• Group headings are hidden from screen readers and label their group instead: "Clients, group".
• The empty message is not announced. If it matters, also update a role="status" region with the result count.
• Shortcuts are hints only. The palette doesn't register them.

RTL

The input, items and group headings align to the right, and the search icon sits at the start. Arrow keys are vertical, so they don't change. The shortcut sits at the far end of each item (ms-auto; upstream used ml-auto, which put it right after the label in RTL). Shortcut text such as "⌘B" stays left to right.

Tokens used

Read from components/ui/command.tsx at build time, so this list changes when the component does. Opacity modifiers such as /90 are shadcn hover and focus tints on top of the token.

• Opacityopacity-(--opacity-disabled)
• Radiusrounded-md
• Radiusrounded-sm
• Typefont-medium
• Typetext-sm
• Typetracking-wide
• Typetext-xs

Props

Command, CommandInput, CommandList, CommandGroup, CommandItem, CommandEmpty and CommandSeparator take the props of the matching cmdk parts: see the cmdk documentation. The useful ones: label (Command, CommandList), filter, shouldFilter and loop (Command), heading (CommandGroup), value, keywords, onSelect and disabled (CommandItem).

Replaces in coach-admin

coach-admin has no command palette today. This is a new capability, not a replacement.

Related

Combobox, Dialog, Popover, Dropdown menu, Sidebar.