CommandPalette

Actions and navigation behind ⌘K, with groups, keywords, shortcut hints and a configurable list of commands.

Installation

Run it from the root of a project already set up with zunoui init.

$ npx zunoui@latest add command-palette

Dependencies

What add command-palette installs alongside the component. The CLI skips any you already have in a compatible version.

ZUNO registry

@zuno/utils
@zuno/command

Examples

1 examples · 1 component

Grouped commands

Press ⌘K or Ctrl+K, or use the button. Try "preferences" to match a keyword.

API reference

Configured through props: pass the commands as data and it renders CommandDialog and Command for you, with ⌘K / Ctrl+K built in.

Prop	Type	Default
`commands` The registry of commands. Groups follow the order in which they first appear; keywords also match the search ("preferences" finds Open settings).	`{ id; label; onSelect; group?; keywords?; shortcut?; disabled? }[]`	—
`onSelect` Runs after the palette closes, so focus is back on the page when the command acts.	`() => void`	—
`shortcut` A hint shown next to the command ("⌘ N"). It does not bind the key: do that where the action lives.	`string`	—
`open / onOpenChange` Controlled open state, for opening it from a button too.	`boolean / (open) => void`	—
`hotkey` Key combination that toggles it; mod is ⌘ on Apple platforms and Ctrl elsewhere. false turns it off.	`string \| false`	`"mod+k"`
`title / placeholder / emptyMessage` Dialog name, search field text and the no-match message.	`string / string / ReactNode`	`"Command palette" / "Type a command or search…" / "No results found."`

States

The states that apply to this component and their visual treatment.

State	Treatment
Closed	Nothing rendered; the hotkey or your button opens it.
Open	The search field focused and every command listed by group.
Filtered	Matches by label or keyword; the first one highlighted.
Empty	The no-match message.

Accessibility

A modal dialog named by title. The search field takes focus on open; Escape closes it and focus returns to what had it before.

Typing filters the commands, the first match is highlighted, arrow keys move and Enter runs the highlighted one.

Group labels are announced with their commands; shortcut hints are decorative, so each command keeps a plain name.

The ⌘K / Ctrl+K hotkey is a document listener: pass hotkey={false} when your app already handles that combination, and show the shortcut on the button that opens it so it can be discovered.

Disabled commands stay visible but can't run, which explains why an action is unavailable better than hiding it.