Command Menu

A searchable list of commands and places in a modal dialog, opened with Cmd+K or Ctrl+K.

The snippet an agent gets

import { CommandMenu } from '@basiiik/ui';<CommandMenu open={open} onOpenChange={setOpen} groups={[{ label: 'Go to', items: [{ value: 'settings', label: 'Settings' }] }]} />

From get_component_snippet, with the required props filled in from the spec. Every snippet is type-checked against the library before it ships.

Example values were filled in for the required props open, onOpenChange, groups: replace them with your own.
Values in braces are your own variables, handlers or data, such as const [open, setOpen] = useState(false).
Results and Empty follow the search; the active option follows the arrow keys and the pointer; open is controlled by the app.
Compose with: kbd.
Storybook: Overlays/Command menu.

Install

npm install @basiiik/uiimport { CommandMenu } from '@basiiik/ui';

Props

Prop	Type	Default
`open`	`boolean`	`Required`
`onOpenChange`	`(open: boolean) => void`	`Required`
`groups`	`CommandMenuGroup[]`	`Required`
`placeholder`	`string`	`–`
`label`	`string`	`–`
`emptyMessage`	`ReactNode`	`–`
`onSelect`	`(item: CommandMenuItem) => void`	`–`
`hideHints`	`boolean`	`–`

Other props

Prop	What it does
`className` `string`

States. Results and Empty follow the search; the active option follows the arrow keys and the pointer; open is controlled by the app.

Accessibility

Cmd+K or Ctrl+K opens it (useCommandMenuShortcut, bound once by the app)
Typing filters the list
Up and Down move the active option (disabled ones are skipped), wrapping at the ends
Enter runs the active option and closes
Escape closes and returns focus to where it was
A modal dialog named "Command menu"; the page behind is inert
The combobox keeps focus; the active option is announced with aria-activedescendant
Groups are role="group" labelled by their heading
The number of results is announced politely while typing
The key hints are aria-hidden (the keyboard instructions are the combobox's own)

Use it when

An app with many pages or actions that people repeat: go to, create, switch
Power users who prefer the keyboard

Do not use it when

Picking a value for a form field (use Combobox)
A short menu of actions on one item (use Dropdown Menu)
The only way to reach a page (keep visible navigation too)

Rules for agents

Pass groups of { label, items }; each item needs a unique value and a label
Give items keywords for the words people might type instead ("new" for "Create project")
Call useCommandMenuShortcut(() => setOpen(true)) once, where the open state lives
Run the action in the item's onSelect; the menu closes on its own
Show a visible way to open it too (a Search button with the shortcut in a Kbd)

Avoid

A hand-built ⌘K modal with its own list and arrow-key code
Binding ⌘K in several places
Items that open another modal without closing the menu first
Using it as the only navigation

Colour tokens it reads

color.bg.subtlecolor.bg.surfacecolor.border.defaultcolor.border.subtlecolor.icon.secondarycolor.text.primarycolor.text.secondarycolor.text.tertiary

2 Figma variantsTry it in the live demo