CommandPalette

Usage examples

import { useState } from 'react';
import { Button } from '@rookcom/monarch-react';
import { CommandPalette, type CommandPaletteItem, type CommandPaletteSource } from '@rookcom/monarch-react/data';

// BoardIcon, ListIcon, PencilIcon, PlusIcon, TrashIcon: demo icons from the docs site; use your own.

/** Built lazily: docs files cannot create JSX at module scope. */
const commands = (): CommandPaletteItem[] => [
  { id: 'new', label: 'Create task', group: 'Actions', icon: <PlusIcon />, shortcut: 'c' },
  { id: 'rename', label: 'Rename', group: 'Actions', icon: <PencilIcon />, shortcut: 'f2' },
  {
    id: 'archive',
    label: 'Archive',
    group: 'Actions',
    icon: <TrashIcon />,
    keywords: ['delete', 'remove'],
    tone: 'danger',
  },
  { id: 'board', label: 'Board', group: 'Go to', icon: <BoardIcon />, shortcut: ['G', 'B'] },
  { id: 'list', label: 'My tasks', group: 'Go to', icon: <ListIcon />, shortcut: ['G', 'M'] },
  {
    id: 'settings',
    label: 'Settings',
    group: 'Go to',
    description: 'Workspace',
    shortcut: 'mod+,',
  },
];

const RECORDS = [
  'Quarterly planning notes',
  'Onboarding checklist',
  'Release checklist',
  'Pricing page copy',
  'Support rota',
  'Quarterly report draft',
];

/** A stand-in for an app's search API: filters sample titles after a short delay. */
const DOCUMENTS: CommandPaletteSource = {
  id: 'documents',
  group: 'Documents',
  minQueryLength: 2,
  search: (query, signal) =>
    new Promise((resolve, reject) => {
      const t = setTimeout(() => {
        resolve(
          RECORDS.filter((r) => r.toLowerCase().includes(query.toLowerCase())).map((r) => ({
            id: r,
            label: r,
            icon: <ListIcon />,
          })),
        );
      }, 350);
      signal.addEventListener('abort', () => {
        clearTimeout(t);
        reject(new DOMException('Aborted', 'AbortError'));
      });
    }),
};

function RecentDemo() {
  const [recent, setRecent] = useState<CommandPaletteItem[]>([
    { id: 'Support rota', label: 'Support rota', icon: <ListIcon /> },
  ]);
  return (
    <CommandPalette
      hotkey={false}
      items={commands()}
      sources={[DOCUMENTS]}
      recent={recent}
      onItemSelect={(item, { page }) => {
        if (page === null && item.group === undefined)
          setRecent((r) => [item, ...r.filter((x) => x.id !== item.id)].slice(0, 5));
      }}
      trigger={<Button variant="secondary">Search documents</Button>}
    />
  );
}

<RecentDemo />

import { useState } from 'react';
import { Button } from '@rookcom/monarch-react';
import { CommandPalette } from '@rookcom/monarch-react/data';

// PencilIcon: demo icon from the docs site; use your own.

function PagesDemo() {
  const [project, setProject] = useState('Website');
  const projects = ['Website', 'Mobile app', 'Design system', 'Internal tools'];
  return (
    <>
      <CommandPalette
        hotkey={false}
        items={[
          { id: 'move', label: 'Move to…', group: 'Task', page: 'move', shortcut: 'm' },
          { id: 'rename', label: 'Rename', group: 'Task', icon: <PencilIcon /> },
        ]}
        pages={{
          move: {
            title: 'Move to',
            placeholder: 'Choose a project…',
            items: projects.map((p) => ({
              id: p,
              label: p,
              disabled: p === project,
              onSelect: () => setProject(p),
            })),
          },
        }}
        trigger={<Button variant="secondary">Task actions</Button>}
      />
      <span>Project: {project}</span>
    </>
  );
}

<PagesDemo />

useHotkey('c', () => openCreateTask());            // ignored while typing
useHotkey(['mod+k', '/'], () => setPaletteOpen(true));
<Kbd>{formatHotkey('mod+shift+p').join('')}</Kbd> // ⌘⇧P or CtrlShiftP

Purpose

Lets keyboard users jump anywhere, run any action or find any record from one search field, without leaving the keyboard. Import from @rookcom/monarch-react/data.

Design principles

• The app owns the data. Commands, recent items and searches are passed in; Monarch owns keyboard, focus, filtering, debouncing, cancellation and announcements.
• One field, one list: the input keeps focus and the active result moves with aria-activedescendant, so typing never stops.
• Results are grouped by kind (“Actions”, “Go to”, “Documents”) with quiet headings; the active row is a muted fill, danger commands are red.
• Shortcut hints sit at the end of each row in Kbd, so the palette teaches the shortcuts it lists.
• Old results stay while new ones load, so the list does not flicker; a spinner replaces the search icon.

API reference

import { CommandPalette, defaultCommandFilter, formatHotkey, isTypingTarget, matchesHotkey, useHotkey } from '@rookcom/monarch-react/data';

Built on Monarch Dialog (Radix Dialog): focus is trapped, the page behind is inert, and focus returns to the trigger on close. Without a trigger, focus returns to where it was.

items, recent and page items are CommandPaletteItems: { id, label, description?, icon?, group?, keywords?, shortcut?, page?, disabled?, tone?, keepOpen?, onSelect? }.

sources are CommandPaletteSources: { id, group, search(query, signal), minQueryLength?, debounceMs? }. Each source is debounced and aborted on its own.

pages maps a key to { title, placeholder?, items?, sources? }; an item with page opens it.

useHotkey(hotkey, handler, { enabled, inFields }), formatHotkey(hotkey), matchesHotkey(event, hotkey) and isTypingTarget(target) are exported for the app’s own shortcuts and shortcut hints.

defaultCommandFilter(item, query) is the default ranking, for apps that wrap it.

App-wide shortcut tables: compose useHotkey; a registry is not part of Monarch yet.

Generated from the TypeScript declarations of packages/react/src/components/search/command-palette.

Properties

Variants

States

Interaction behaviour

• The hotkey (default mod+k: ⌘K on Apple platforms, Ctrl+K elsewhere) toggles the palette from anywhere. Pass an array for alternatives such as ["mod+k", "/"], or false to bind it yourself.
• Single-key hotkeys such as / never fire while typing in a field or contenteditable; modified ones do unless hotkeyInFields={false}. Keys during IME composition are ignored.
• Every open starts on the first page with an empty query. With an empty query the recent group comes first.
• Typing filters items with the default ranking (every word must match label, description or keywords; label prefixes first) or your filter. Groups keep the order their first item appears in; ungrouped items come first.
• Each source waits debounceMs (200) after the last keystroke, searches once the trimmed query is minQueryLength (1) long, and aborts its request when the query, page or open state changes.
• Choosing an item runs its onSelect, then onItemSelect, then opens its page, or closes the palette unless keepOpen.
• Pointer: moving over a row makes it active; clicking runs it. Rows never take focus.

Keyboard support

Home and End stay with the input (caret to start or end), as in the APG combobox pattern.

Accessibility

Role

dialog containing combobox + listbox (option, group)

Accessible name

The dialog and input are named by messages.title (“Command palette”); the listbox by messages.results; each group by its heading.

• APG combobox with listbox popup: the input has aria-expanded="true", aria-controls and aria-activedescendant; the active option has aria-selected="true".
• Result count, “No results” and “Searching…” are announced through a polite live region after results settle.
• Shortcut hints and icons are aria-hidden, so an option’s name is its label and description.
• The default footer is aria-hidden: it repeats the keyboard model for sighted users only.
• Verified with axe in jsdom (open, empty and nested-page states) and in Chromium, Firefox and WebKit on /components/command-palette.

Responsive behaviour

• Up to 40rem wide, near the top of the viewport, capped at 34rem tall; the result list scrolls.
• Below 640px it fills the screen (Dialog fullScreenOnPhone), keeping clear of notches, and hides shortcut hints and the default footer.
• Rows grow to --mn-control-lg on coarse pointers so they are easy to tap.

Theme support

• Monarch semantic tokens only: the raised surface and border of Dialog, --mn-color-bg-muted for the active row, --mn-color-danger-* for danger rows.
• In forced-colours mode the active row gets a Highlight outline.
• The entrance animation is removed under prefers-reduced-motion: reduce.

Do and don't

Related components

• Combobox: Picks a value for a form field; the palette runs commands and navigates.
• Dialog: The modal the palette is built on.
• Kbd: Draws the shortcut hints and footer keys.
• SearchInput: Filters the list on the current page instead.

Dependencies

Testing coverage

• The hotkey opens it; dialog, combobox, listbox and named groups are wired (aria-controls, aria-activedescendant, aria-selected); axe in open, empty and nested-page states.
• Arrow keys skip disabled results and wrap; Enter runs onSelect and onItemSelect and closes; PageUp/PageDown jump; keepOpen keeps it open; pointer hover moves the active row.
• Filtering by label, description and keywords with ranking; empty state announced.
• Recent group shows only with an empty query.
• Shortcut hints render as Kbd and stay out of the option name; default footer hints.
• Nested pages: placeholder, renamed input, back chip; Backspace and Escape leave the page before Escape closes; selections report their page.
• Async sources: minimum length, one debounced request per settled query, stale results kept while loading, the previous request aborted on new input and on close, error with Retry.
• Hotkey: single keys ignored in fields, modified keys work in fields unless hotkeyInFields={false}, hotkey={false} turns it off, it toggles closed.
• Controlled open and search, a trigger, and a fresh query on reopen.
• Helpers: formatHotkey per platform, matchesHotkey with symbols and Shift, isTypingTarget, defaultCommandFilter ranking and accent folding.
• Renders on the server.

Tests: packages/react/src/components/search/command-palette