CommandPalette

CommandPalette

const commands: Command[] = [
  { id: 'goto-dashboard', label: 'Go to dashboard', group: 'Navigation', onAction: (close) => { router.push('/'); close(); } },
  { id: 'new-project',    label: 'New project',     group: 'Actions',    keywords: ['create'], onAction: (close) => { openNewProject(); close(); } },
  { id: 'theme-toggle',   label: 'Toggle theme',    group: 'Settings',   onAction: (close) => { toggleTheme(); close(); } },
];

<CommandPalette commands={commands} />

Press Cmd+K (Mac) or Ctrl+K (Windows/Linux) to open.

Install: @helixui/core

import { CommandPalette, type Command } from '@helixui/core'

status: beta · since: 0.2.0

Tags: cmd-k, search, actions, modal, productivity

Anatomy

┌─ overlay ────────────────────────────────┐
│  ┌── modal ───────────────────────────┐  │
│  │  > search                          │  │
│  │  ─────────────                     │  │
│  │  Section                           │  │
│  │   • action 1   ⌘K                  │  │
│  │   • action 2                       │  │
│  │  Section                           │  │
│  │   • action 3                       │  │
│  └────────────────────────────────────┘  │
└──────────────────────────────────────────┘

Layout

• display — portal
• width — fixed:560px
• height — content
• intrinsicSize — centered modal, max-h ~60vh
• stackable — false
• fullBleed — false

Visual

A centered modal with a top search input and a scrollable list of grouped commands beneath. Arrow keys navigate, Enter activates, ⌘K opens. Each item shows an optional icon, label, and shortcut hint.

Props

Name	Type	Default	Description
commands	Command[]	—	Required. Each command has id, label, optional group, hint, keywords, icon, and an onAction(close) handler.
isOpen	boolean	—	Controlled visibility.
defaultOpen	boolean	false	Uncontrolled initial visibility.
onOpenChange	(open: boolean) => void	—	Visibility change handler.
shortcut	string	Mod+k	Global keyboard shortcut to open. Mod = Cmd on Mac, Ctrl elsewhere.
placeholder	string	Type a command…	Search input placeholder.
emptyMessage	ReactNode	No matches.	Shown when no commands match the query.

Tokens used

color.bg.surface.default, color.bg.action.neutral.default, color.bg.action.brand.subtle, color.border.default, color.text.primary, color.text.secondary, color.text.muted, color.text.action.brand, radius.lg, radius.md, radius.sm, space.2, space.3, space.4, space.6, font.family.sans, font.family.mono, font.size.xs, font.size.sm, font.size.md, font.weight.semibold, shadow.lg

Accessibility

Keyboard

Key	Action
Mod+k	Open palette globally.
ArrowDown	Next command.
ArrowUp	Previous command.
Enter	Run highlighted command.
Escape	Close palette.

Notes

• The input is role="combobox"; the list is role="listbox"; items are role="option". The active item is announced via aria-activedescendant.

Composes with

Component	Relation	Note
Menu	alternative	Menu is anchored to a trigger; CommandPalette is global.
Dialog	alternative	Dialog is for tasks; CommandPalette is for actions.
Popover	sibling

Prompt examples

These are the AI prompt → JSX mappings used by the helixui prompt DSL and integrations like Cursor / Claude Code.

global cmd-k

“cmd+k command palette with two sections”

<CommandPalette
  isOpen={open}
  onOpenChange={setOpen}
  commands={[
    { group: 'File', items: [{ id: 'new', label: 'New file', onPress: createFile }] },
    { group: 'Help', items: [{ id: 'docs', label: 'Open docs', onPress: openDocs }] },
  ]}
/>

Related

• Menu
• Dialog
• Popover