Skip to content
quartiledocsv0.1
GitHub

CommandMenu

Preview

A command palette in a modal dialog: a search field that filters grouped commands. This site’s ⌘K search is built on it.

Example

const groups: CommandGroup[] = [
  {
    label: 'Add a chart',
    items: [
      { label: 'Line chart', icon: <IconLineChart />, keywords: ['trend'], onSelect: addLine },
      { label: 'Bar chart', icon: <IconBarChart />, keywords: ['compare'], onSelect: addBar },
      { label: 'Table', icon: <IconTable />, keywords: ['rows'], onSelect: addTable },
    ],
  },
  {
    label: 'Actions',
    items: [
      { label: 'Export PDF', icon: <IconFile />, shortcut: '⌘E', onSelect: exportPdf },
      { label: 'Copy link', icon: <IconCopy />, onSelect: copyLink },
    ],
  },
];

<Button icon={<IconSearch />} onClick={() => setOpen(true)}>Open command menu</Button>
<CommandMenu open={open} onOpenChange={setOpen} groups={groups} placeholder="Search commands…" />

Usage

Items match on their label (or textValue) and keywords. Running an item calls its onSelect, closes the menu and returns focus. shortcut is display only; wire real shortcuts with useHotkey, which matches ⌘ on macOS and Ctrl elsewhere:

import { useHotkey } from '@quartile/react';

useHotkey('mod+k', () => setOpen((o) => !o));

Pass query and onQueryChange to rank results yourself, as this site's search does. CommandPalette is the same list without the dialog.

Props

CommandMenu

PropTypeDefaultDescription
openrequiredboolean——
onOpenChangerequired(open: boolean) => void——
titlestring'Command menu'Names the dialog (default "Command menu").
classNamestring——
placeholderstring——
labelstring—Names the search field for assistive technology.
groupsrequiredCommandGroup[]——
querystring——
defaultQuerystring——
onQueryChange(query: string) => void——
emptyMessageReactNode—Shown when nothing matches.

Also accepts the props of Omit<CommandPaletteProps, 'onItemSelect' | 'autoFocus' | 'escHint'>, spread onto the root element.

CommandGroup

PropTypeDefaultDescription
labelrequiredstring——
itemsrequiredCommandItem[]——

CommandItem

PropTypeDefaultDescription
labelrequiredReactNode——
iconReactNode——
shortcutReactNode—Display-only hint: ↵, ⌘E.
keywordsstring[]—Extra words that should match the query: synonyms, the action's verb.
textValuestring—Text to match when label is not a string.
disabledboolean——
onSelect() => void——

Accessibility

  • A modal dialog named by title; focus moves to the search field.
  • ↑ ↓ move the highlight, Enter runs the command, Escape or a click outside closes.
  • Name the search field with label when the placeholder is not enough.
Report an issueBuilt Oct 21, 2026