Command Palette
Prov1.0.0A ⌘K palette for jumping and acting, with previews and nested steps.
Build for your project
Code/install build
Usage
Import it and pass your content. The props that matter most are listed next.
Example
"use client";
import { CommandPalette, type PaletteItem } from "@/components/ui/notchset/blocks/command-palette";
const items: PaletteItem[] = [
{ id: "planner", group: "AGENTS", title: "Planner", glyph: "PL", kind: "AGENT", action: "OPEN AGENT" },
{ id: "pause", group: "ACTIONS", title: "Pause Planner", glyph: ">", kind: "ACTION", action: "PAUSE", prefix: ">", onRun: () => "PLANNER PAUSED" },
];
export function Commands() {
return <CommandPalette items={items} />;
}Props
items–{ id, group, title, glyph, round?, kind, meta?, description?, facts?, action, shortcut?, prefix?, step?, onRun? }[]Everything it can find. prefix makes an item answer to a scope; step opens nested items instead of running; onRun returns a confirmation.
recent–string[]Ids shown under RECENT while the query is empty.
scopes{ ">": "ACTIONS", "#": "RUNS", "@": "PEOPLE" }Record<string, string>Prefixes and the chip each shows.
open / defaultOpen / onOpenChange–boolean⌘K inside the block toggles it.
triggerLabel / hint / placeholder–stringThe trigger, the line under it until something runs, and the input's hint.
Anatomy
- One block over your items.
- Scopes and nested steps come from item fields, not separate components.
- Every item can confirm what it did.
CommandPalettedata-slot="command-palette"The trigger and the palette.
Source
components/ui/notchset/blocks/command-palette.tsx
This component is included with Pro.
Try the live preview above. Get Pro to install the source.
Build for your project
Code/install build
Installation
pnpm dlx shadcn@latest add @beautiful-ui-pro/command-paletteNeeds your registry key. Your components.json style picks the Base UI or Radix build: radix-*, new-york and default get Radix, base-* gets Base UI.
Styles didn't apply?
The CLI adds the styles to the CSS file named in components.json (tailwind.css). Check that it points at your global stylesheet, that the project uses Tailwind CSS v4, and that the file is imported in your root layout. Installed by hand: paste styles.css into that file.
For coding agents
Give your coding assistant the Markdown guide instead of screenshots.
Use it for
- Keyboard-first navigation and actions in an app with many objects (agents, runs, people)
- Actions that need a second choice (a model, a target) without leaving the keyboard
Use something else when
- A search over thousands of records: filter on the server and pass the results in
- A site-wide docs search: a simpler palette fits
Mistakes to avoid
- Keep titles short: the match highlights letters in the title only
- Return a confirmation from onRun so the result is said, not assumed
Agents find it by
- command palette, command menu, cmd k, quick switcher, spotlight search, keyboard launcher, fuzzy search, Notchset
Where agents read it
- Guide for this component: https://beautiful-ui.dev/md/command-palette.md
- Every component, for tools without MCP: /llms.txt
- MCP server:
https://beautiful-ui.dev/api/mcp(setup)
Behaviour
Keyboard
- ⌘K / Ctrl+K
- Open or close
- ↑ ↓
- Move the highlight
- Enter
- Run the item or open its step (ignored while composing with an IME)
- Esc / ⌫ on an empty step
- Back out of a step, then close
Accessibility
- The palette is a modal dialog; its input is a combobox over a listbox with aria-activedescendant
- The preview is a labelled, polite live region; the confirmation under the trigger is announced
- Focus returns to the trigger when the palette closes
Motion
- Open
- Scales from .98 and fades (280ms) over a scrim; closes faster (180ms)
- Highlight
- One block glides between rows (160ms); the selected glyph inverts
- Preview
- Cross-fades as the selection moves (200ms)
- Count
- The result count rolls
Responsive
- The preview hides under 640px of block width; the dialog keeps 16px from the edges.
Performance
- Matching runs over the items you pass on every keystroke; past a few hundred, filter on the server and pass the hits.
Changelog
v1.0.0 · 2026-10-03
First release
Part of
Included with Pro
Pro is in early access.
