Command Palette

A command palette modal (Cmd/Ctrl+K) for quick actions and navigation with search, grouping, and full keyboard accessibility

Installation

Install the Command Palette component using the nocta-ui CLI:

npx nocta-ui add command-k

Import the component:

import { CommandK } from '@/components/ui/command-k';

Example

The Command Palette provides a fast, searchable modal for navigating and triggering actions using the keyboard.

Or press ⌘K / Ctrl+K

Keyboard Shortcuts

Open: platform-default ⌘K (macOS) / Ctrl+K (Windows/Linux)
Navigate: ↑/↓
Confirm: Enter
First/Last: Home / End
Close: Escape

Customizing the open hotkey

// Require Cmd+P on macOS, Ctrl+P on Windows/Linux
<CommandK hotkey={{ key: 'p' }} />

// Explicit modifier (always Cmd)
<CommandK hotkey={{ key: 'k', metaKey: true }} />

// Explicit modifier (always Ctrl)
<CommandK hotkey={{ key: 'k', ctrlKey: true }} />

Controlled vs Hotkey

You can control visibility with open/onOpenChange or rely solely on the global hotkey.

const [open, setOpen] = useState(false);

<CommandK open={open} onOpenChange={setOpen} items={items} />

// No local state — palette opens with Cmd/Ctrl+K
<CommandK items={items} />

API Reference

CommandK

Prop	Type	Default	Description
`items`	`CommandKItem[]`	—	List of entries to render
`open`	`boolean`	—	Controlled open state
`defaultOpen`	`boolean`	`false`	Initial open state
`onOpenChange`	`(open: boolean) => void`	—	Callback when open state changes
`placeholder`	`string`	`'Type a command or search...'`	Search input placeholder
`emptyMessage`	`string`	`'No results'`	Message when no results match
`closeOnAction`	`boolean`	`true`	Close palette after selection
`size`	`'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'`	`'xl'`	Dialog size variant
`className`	`string`	`''`	Extra classes for DialogContent wrapper
`listClassName`	`string`	`''`	Extra classes for results list
`autoFocus`	`boolean`	`true`	Focus search input when opened
`hotkey`	`{ key: string; metaKey?: boolean; ctrlKey?: boolean; }`	`{ key: 'k' }`	Open shortcut; when no modifier specified, uses platform default (⌘/Ctrl)
`onSelect`	`(item: CommandKItem) => void`	—	Called on item selection

CommandKItem

Prop	Type	Default	Description
`id`	`string`	auto	Optional unique ID
`label`	`string`	—	Display label
`group`	`string`	`'General'`	Group header label
`description`	`string`	`''`	Secondary description text
`keywords`	`string[]`	`[]`	Additional searchable terms
`icon`	`React.ReactNode`	—	Optional icon
`shortcut`	`string[]`	`[]`	Visual shortcut hints
`disabled`	`boolean`	`false`	Disable selection
`action`	`() => void`	—	Action executed on select

On this page