Command palette
A complete keyboard driven action surface with search, grouped results, and shortcuts.
pnpm dlx shadcn@latest add @uiarc/command-palettePattern · live
- App-wide command search opened with Cmd or Ctrl plus K.
- Jumping to pages, creating items, and running actions from one input.
- Inline search panels that group results with shortcuts.
- Use combobox to pick a value inside a form.
- Use dropdown-menu for a short list of actions.
- Use expanding-search or search-field to search page content.
Installation
Add Command palette with the shadcn CLI, or copy the source by hand.
pnpm dlx shadcn@latest add @uiarc/command-paletteAdds the block and its local dependencies, and installs motion, lucide-react. First time? Add the @uiarc registry to components.json, or use the full URL:
Usage
Use it for product wide actions and navigation. Provide meaningful groups, icons, keyboard shortcuts, and handlers.
example.tsx
import { CommandPalette, type CommandItem } from "@/components/arc/command-palette/command-palette"; const items: CommandItem[] = [ { id: "new", label: "New project", group: "Create", shortcut: "N" }, { id: "invite", label: "Invite teammate", group: "Team", keywords: ["member"] }, { id: "theme", label: "Toggle theme", description: "Switch light and dark" },]; export function Palette({ onClose }: { onClose: () => void }) { return <CommandPalette items={items} onSelect={item => run(item.id)} onClose={onClose} />;}Built fromSearchKeyboard navigationAction list
Inside a dialog
example.tsx
<Dialog open={open} onOpenChange={setOpen}> <DialogContent title="Command palette"> <CommandPalette items={items} onSelect={item => { run(item.id); setOpen(false); }} onClose={() => setOpen(false)} /> </DialogContent></Dialog>API reference
2 parts. The first is the root.
CommandPalette
An inline search-and-run panel: a combobox input over grouped, filtered results with one highlight that follows the active row.
PropTypeDefaultDescription
itemsRequiredCommandItem[]–Commands to search. Every word of the query must match: anywhere in the label, at a word start in the description or keywords, or as letters in order across the label ("shpr" finds Share project). Label prefixes rank first, groups follow their best match, and the matched letters render in medium weight.placeholderstring"Search commands"Input placeholder.onSelect(item: CommandItem) => void–Called on click or Enter. The query then clears and focus returns to the input.onClose() => void–Called on Escape with an empty query. Also renders an Esc close button.labelstring"Command palette"Visually hidden label for the input.autoFocusbooleanfalseFocuses the search input on mount, for a palette that opens on demand.CommandItem
Item type: { id: string; label: string; description?: string; group?: string; keywords?: string[]; icon?: ReactNode; shortcut?: string }. Items without a group land under Actions. A shortcut such as "⇧ N" or "Shift+N" renders one keycap per key.
No props.
- Cmd/Ctrl+K
- Focuses the search input from anywhere on the page.
- ArrowDownorArrowUp
- Moves the active result.
- HomeorEnd
- Jumps to the first or last result.
- Enter
- Runs the active result. The first result is active as soon as results show.
- Escape
- Clears the query, or calls onClose when it is already empty.
- The input is a combobox with aria-controls and aria-activedescendant pointing at the listbox option, so focus never leaves the input.
- Results are role=option buttons with aria-selected, grouped in labelled role=group containers.
- A polite live region announces the result count, or No results, as the query changes.
- It renders inline, not in a modal. Put it in a dialog yourself if it should trap focus and close on outside click.
- The panel rises in on a spring; the results frame springs to the list height as the query filters.
- Remaining rows glide into place when the shift is small and snap when it is a long jump; the highlight follows the active row on the snappy spring for pointer and arrow keys.
- Reduced motion removes the entrance, glides, and highlight travel.
- It fills its container width; below 480px shortcut hints are hidden and padding tightens.
- Below 340px the footer drops its last hint.
- Results scroll inside a 342px maximum height, and long labels ellipsize.
- Filtering is a simple substring match over label, description, group, and keywords on every keystroke.
- Rows are not virtualized and animate with layout; keep lists to a few hundred items or filter on the server.
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
- Use for app-wide command search. For picking a value inside a form use combobox; for a small list of actions use dropdown-menu.
- Wrap it in dialog and pass onClose to close the dialog; map onSelect to your router or action handlers by item.id.
The full library index for assistants is at /llms.txt.
Selection toolbarProBlockA contextual batch action surface that appears when items are selected.SidebarProBlockApp and docs sidebars: a folding rail, a workspace switcher, a mail shell, and a docs tree.Search resultsProBlockA faceted workspace search page with suggestions, facet counts that follow the query, filter chips, mixed doc, person and file results with highlighted matches, a gliding keyboard cursor and a preview pane.