A command palette: a search box over grouped actions with shortcuts, keyboard-first, inline or as a Ctrl+K dialog.
Command is a combobox over a grouped listbox. Typing filters every group (every word must appear in the label or the item's keywords), Up and Down move the highlight, Enter runs it, and an empty state says when nothing matches. Focus stays in the input throughout; the highlighted option is announced through aria-activedescendant.
CommandDialog lifts it over the page in the modal glass and toggles it with Ctrl+K or Cmd+K (shortcut, on by default). Running a command closes it; Esc and the scrim close it too, and focus returns to where it was.
inline renders the open panel in the page flow: no portal, scrim, focus trap, scroll lock or outside-click listener. It exists for docs, previews and static mock-ups; never ship it as the live overlay.
Installation
npx shadcn@latest add KezLahd/rime/commandAlso installs: alert-dialog, base, icon, scroll-area.
Usage
import { Command, CommandDialog } from "@/components/ui";
<CommandDialog
open={open}
onOpenChange={setOpen}
groups={[
{ heading: "Suggestions", items: [{ id: "invoice", label: "Create invoice", shortcut: "Ctrl N", onSelect: create }] },
{ heading: "Go to", items: [{ id: "orders", label: "Orders", onSelect: () => router.push("/orders") }] },
]}
/>Examples
Palette
As a dialog with Ctrl+K
API
Generated from the component's TypeScript types and JSDoc (scripts/gen-ui-registry.mjs), so it always matches the source.
Command
| Prop | Type | Default | Description |
|---|---|---|---|
| groupsRequired | ReadonlyArray<CommandGroup> | ||
| label | string | "Search commands" | The input's accessible name. |
| placeholder | string | "Type a command or search…" | |
| emptyText | ReactNode | "No results found." | Shown when nothing matches. |
| onSelect | (item: CommandItem) => void | Called with the item after its own onSelect runs. | |
| query | string | Controlled query. Leave unset for uncontrolled. | |
| onQueryChange | (q: string) => void | ||
| autoFocus | boolean | Focus the input on mount. | |
| className | string |
CommandDialog
| Prop | Type | Default | Description |
|---|---|---|---|
| label | string | The input's accessible name. | |
| className | string | ||
| onSelect | (item: CommandItem) => void | Called with the item after its own onSelect runs. | |
| placeholder | string | ||
| groupsRequired | ReadonlyArray<CommandGroup> | ||
| emptyText | ReactNode | Shown when nothing matches. | |
| query | string | Controlled query. Leave unset for uncontrolled. | |
| onQueryChange | (q: string) => void | ||
| openRequired | boolean | ||
| onOpenChangeRequired | (open: boolean) => void | ||
| shortcut | boolean | true | Toggle with Ctrl+K or Cmd+K from anywhere on the page. On by default. |
| inline | boolean | Render the open palette in the page flow: no portal, scrim, focus trap or shortcut (docs, previews). |
Theme tokens
Per-component tokens are undeclared by default, so the default shown is the fallback the CSS uses. Set one at :root (or in theme.css) to restyle every instance. Live values are read from this page, so they follow the Rime Studio.
| Token | Default | Live value |
|---|---|---|
| --command-dialog-width | 560px | … |
| --command-input-h | 48px | … |
| --command-list-max | 320px | … |
| --command-radius | var(--r-lg) | … |
| --command-width | 440px | … |
| --popover-item-active-bg | linear-gradient(to right, rgba(var(--rgb-brand), 0.14), rgba(var(--rgb-brand-deep), 0.07)) | … |
| --popover-item-radius | var(--r-xs) | … |
| --popover-pad | calc(6px * var(--density)) | … |
System tokens it reads
| Token | Default | Live value |
|---|---|---|
| --border-w | tokens.css | … |
| --density | tokens.css | … |
| --dur | tokens.css | … |
| --dur-slow | tokens.css | … |
| --ease | tokens.css | … |
| --ease-out | tokens.css | … |
| --font-body | tokens.css | … |
| --ink-body | tokens.css | … |
| --ink-brand | tokens.css | … |
| --ink-disabled | tokens.css | … |
| --ink-heading | tokens.css | … |
| --ink-muted | tokens.css | … |
| --ink-placeholder | tokens.css | … |
| --line | tokens.css | … |
| --line-glass | tokens.css | … |
| --line-soft | tokens.css | … |
| --modal-blur | tokens.css | … |
| --modal-scrim | tokens.css | … |
| --modal-scrim-blur | tokens.css | … |
| --modal-shadow | tokens.css | … |
| --modal-surface | tokens.css | … |
| --popover-blur | tokens.css | … |
| --popover-border | tokens.css | … |
| --popover-shadow | tokens.css | … |
| --popover-surface | tokens.css | … |
| --r-2xs | tokens.css | … |
| --r-lg | tokens.css | … |
| --r-xs | tokens.css | … |
| --rgb-brand | tokens.css | … |
| --rgb-brand-deep | tokens.css | … |
| --rgb-white | tokens.css | … |
| --text-caption | tokens.css | … |
| --text-input | tokens.css | … |
| --text-micro | tokens.css | … |
| --text-small | tokens.css | … |
| --tracking-label | tokens.css | … |
| --z-modal | tokens.css | … |
Accessibility
- The input is role="combobox" with aria-controls and aria-activedescendant; results are role="listbox" with role="group" sections labelled by their headings and role="option" rows.
- The result count is announced through a polite status region as you type.
- CommandDialog is a modal dialog: focus moves to the input, Tab is trapped, Esc closes, focus returns.
Do and don't
Do
- Add keywords for the words people actually type ("new", "add").
- Show the real shortcut beside each command that has one.
Don't
- Don't make the palette the only way to reach a page.
- Don't fill it with every possible action; keep the top group to what is likely now.
For AI agents
This page as markdown, rendered from the same registry entry. Point an agent at it (or add .md to this page's URL), or at /llms.txt for the index.
Open command.mdRelated: nav-search, menu