CommandMenu
Cmd+K command palette with fuzzy search over grouped commands
Category: overlay · WCAG 2.2-AA · overlay, command, palette, search, cmdk, keyboard, scope, fuzzy
States
- closed
- open
Props
| Prop | Type | Default | Description |
|---|---|---|---|
open | boolean | — | Whether the component is open (controlled). |
onOpenChange | (open: boolean) => void | — | Called with the next open state when it changes. |
groups | CommandGroup[] | — | The grouped commands to display. |
placeholder | string | Type a command or search… | Placeholder text shown when the field is empty. |
emptyLabel | string | No results found | Text shown when no commands match the query. |
hotkey | boolean | true | Global Cmd/Ctrl+K toggles the menu via onOpenChange |
label | string | Command menu | Text label for the control. |
loading | boolean | false | Shows a loading spinner in place of the empty state (for async items) |
onQueryChange | (query: string) => void | — | Fires on every query keystroke — use to fetch async items |
scopes | CommandScope[] | [] | Selectable filter scopes. Renders a scope bar + chip; a scope activates by clicking its pill, typing its prefix (c:/c ), or cycling with Tab, and filters to groups tagged with a matching scope (plus untagged groups). |
className | string | — | Additional CSS class names merged onto the root element. |
Design tokens
--cascivo-color-surface-overlay--cascivo-color-border--cascivo-color-bg-subtle--cascivo-color-text--cascivo-color-text-muted--cascivo-color-text-subtle--cascivo-color-accent-content--cascivo-color-accent-muted--cascivo-color-accent-subtle--cascivo-color-success-subtle--cascivo-color-success-foreground--cascivo-color-warning-subtle--cascivo-color-warning-foreground--cascivo-font-mono--cascivo-radius-modal--cascivo-radius-sm--cascivo-shadow-xl--cascivo-motion-enter--cascivo-motion-exit
When to use
- Giving power users a global Cmd/Ctrl+K palette to search and run actions or navigate
- Exposing many commands across grouped categories that benefit from fuzzy search
- Multi-step flows where selecting an item drills into a nested page of further commands
When not to use
- Picking a form value from a list — use Combobox
- A small set of actions tied to a specific trigger button — use Dropdown
How to build an accessible CommandMenu in React →
Examples
Basic command menu
<CommandMenu
open={open}
onOpenChange={setOpen}
groups={[
{
heading: 'Actions',
items: [
{ id: 'new', label: 'New file', shortcut: ['⌘', 'N'], onSelect: createFile },
{ id: 'search', label: 'Search docs', keywords: ['find'], onSelect: openSearch },
],
},
]}
/>Scoped search with rich rows and inline actions
A scope chip filters to Clusters, matched glyphs are highlighted, each row carries a mono metadata line + status pill, and the selected row reveals Open (↵) / New tab (⌘↵) inline actions.
<CommandMenu
open={open}
onOpenChange={setOpen}
scopes={[
{ id: 'clusters', label: 'Clusters', prefix: 'c' },
{ id: 'orgs', label: 'Orgs', prefix: 'o' },
{ id: 'commands', label: 'Commands', prefix: '>' },
]}
groups={[
{
heading: 'Clusters',
scope: 'clusters',
items: [
{
id: 'prod-eu',
label: 'prod-eu-central-1',
description: 'eu-central-1 · Enterprise · c9f21a04',
status: { label: 'Healthy', tone: 'healthy' },
actions: [
{ id: 'open', label: 'Open', shortcut: ['↵'], onSelect: () => open('prod-eu') },
{ id: 'tab', label: 'New tab', shortcut: ['⌘', '↵'], onSelect: () => openInTab('prod-eu') },
],
},
],
},
]}
/>