CommandMenu

Tier: ownUnstable

ImportCopy Anchor Link

import { CommandMenu } from '@nizivo/react/unstable/command-menu';

// Once per app (Getting started), after
// @nizivo/tokens/tokens.css and @nizivo/react/css/base.css and @nizivo/react/css/dialog.css and @nizivo/react/css/kbd.css
import '@nizivo/react/css/command-menu.css';

UnstableCopy Anchor Link

It ships at @nizivo/react/unstable/command-menu, outside the semver promise. Still to come: results that load as the reader types (async sources), a cap per group, a long list that renders only what shows, a spoken count of the results, and loading the menu only on the first ⌘K.

Static or interactiveCopy Anchor Link

Client. It is the Dialog with React Aria's Autocomplete inside. The server renders the trigger; the dialog renders only after hydration, when it opens. How to choose.

PartsCopy Anchor Link

CommandMenu.Root holds whether it is open and registers its shortcut (hotkey, 'mod+k' by default; null for none). CommandMenu.Trigger opens it from the pointer and touch, and names the shortcut through aria-keyshortcuts. CommandMenu.Popup is the dialog; in it, CommandMenu.Input (the search row, with an "esc" hint), CommandMenu.List of CommandMenu.Groups with a heading and their CommandMenu.Items, and CommandMenu.Footer, the keys as Figma shows them.

RowsCopy Anchor Link

An item is a link (href) or an action (onAction, in a client component); choosing it closes the menu. icon draws a 20 px mark before its text, kind says what it is at the row's end ("Product", "Order"), and shortcut draws its own Kbd and announces it. The search matches textValue, or the item's text when it is a string. filter on the Popup is 'contains' (default) or 'startsWith'.

ShortcutsCopy Anchor Link

The menu's shortcut is registered in @nizivo/react/hotkeys, one list for the whole page that a help dialog can read with useHotkeys. useHotkey and registerHotkey add your own: they never fire during an IME composition or while the reader types in a field, unless allowInInputs, and a single printable key with no modifier warns in development (WCAG 2.1.4).

ExamplesCopy Anchor Link

import type { JSX } from 'react';
import { Button } from '@nizivo/react/button';
import { CommandMenu } from '@nizivo/react/unstable/command-menu';

/** Stand-ins for `@nizivo/icons` glyphs. */
function Box(): JSX.Element {
  return (
    <svg viewBox="0 0 24 24" width="1em" height="1em" fill="none" stroke="currentColor">
      <path d="M4 7l8-4 8 4v10l-8 4-8-4z" />
    </svg>
  );
}

function Sheet(): JSX.Element {
  return (
    <svg viewBox="0 0 24 24" width="1em" height="1em" fill="none" stroke="currentColor">
      <path d="M6 3h12v18H6zM9 8h6M9 12h6" />
    </svg>
  );
}

function Plus(): JSX.Element {
  return (
    <svg viewBox="0 0 24 24" width="1em" height="1em" fill="none" stroke="currentColor">
      <path d="M12 5v14M5 12h14" />
    </svg>
  );
}

export function CommandMenuExample(): JSX.Element {
  return (
    <CommandMenu.Root>
      <CommandMenu.Trigger render={<Button variant="secondary">Search…</Button>} />
      <CommandMenu.Popup>
        <CommandMenu.Input placeholder="Search products, orders and actions" />
        <CommandMenu.List>
          <CommandMenu.Group heading="Products">
            <CommandMenu.Item href="#stoneware-mug" icon={<Box />} kind="Product">
              Stoneware mug
            </CommandMenu.Item>
            <CommandMenu.Item href="#stoneware-bowls" icon={<Box />} kind="Product">
              Stoneware bowl set
            </CommandMenu.Item>
          </CommandMenu.Group>
          <CommandMenu.Group heading="Orders">
            <CommandMenu.Item href="#order-1042" icon={<Sheet />} kind="Order">
              #1042 · Stoneware mug ×2
            </CommandMenu.Item>
          </CommandMenu.Group>
          <CommandMenu.Group heading="Actions">
            <CommandMenu.Item href="#new-product" icon={<Plus />} kind="Action" shortcut="mod+n">
              Create product
            </CommandMenu.Item>
            <CommandMenu.Item
              href="#new-discount"
              icon={<Plus />}
              kind="Action"
              shortcut="mod+shift+d"
            >
              Create discount
            </CommandMenu.Item>
          </CommandMenu.Group>
        </CommandMenu.List>
        <CommandMenu.Footer />
      </CommandMenu.Popup>
    </CommandMenu.Root>
  );
}

Other exportsCopy Anchor Link

CommandMenuFilter type

import type { CommandMenuFilter } from '@nizivo/react/unstable/command-menu'

How the typed text matches an item's text: anywhere in it, or at its start; case and accents ignored.

type CommandMenuFilter = "contains" | "startsWith"

CommandMenuFooterProps type

import type { CommandMenuFooterProps } from '@nizivo/react/unstable/command-menu'

The props of CommandMenu.Footer, listed above.

CommandMenuGroupProps type

import type { CommandMenuGroupProps } from '@nizivo/react/unstable/command-menu'

The props of CommandMenu.Group, listed above.

CommandMenuInputProps type

import type { CommandMenuInputProps } from '@nizivo/react/unstable/command-menu'

The props of CommandMenu.Input, listed above.

CommandMenuItemProps type

import type { CommandMenuItemProps } from '@nizivo/react/unstable/command-menu'

The props of CommandMenu.Item, listed above.

CommandMenuItemState type

import type { CommandMenuItemState } from '@nizivo/react/unstable/command-menu'

Name	Type	Default	Description
disabledrequired	boolean	–
focusVisiblerequired	boolean	–
highlightedrequired	boolean	–	The active row: the arrow keys or the pointer are on it.

CommandMenuLabels type

import type { CommandMenuLabels } from '@nizivo/react/unstable/command-menu'

CommandMenu's own strings (§16.4): serialisable, English defaults.

Name	Type	Default	Description
emptyrequired	string	'No results'	Shown when nothing matches.
labelrequired	string	'Command menu'	The dialog's and the search field's name.
navigaterequired	string	'Navigate'	The footer's arrow keys hint.
openrequired	string	'Open'	The footer's Enter hint.
placeholderrequired	string	'Search'	The search field's placeholder.

CommandMenuListProps type

import type { CommandMenuListProps } from '@nizivo/react/unstable/command-menu'

The props of CommandMenu.List, listed above.

CommandMenuPopupProps type

import type { CommandMenuPopupProps } from '@nizivo/react/unstable/command-menu'

The props of CommandMenu.Popup, listed above.

CommandMenuRootProps type

import type { CommandMenuRootProps } from '@nizivo/react/unstable/command-menu'

The props of CommandMenu.Root, listed above.

CommandMenuTriggerProps type

import type { CommandMenuTriggerProps } from '@nizivo/react/unstable/command-menu'

The props of CommandMenu.Trigger, listed above.

Data attributes and slotsCopy Anchor Link

Style parts by class (.nz-<slot>) and state by data attribute. Attribute meanings come from contracts/vocabulary.json.

CSS hooksCopy Anchor Link

Set a hook on the component's class or any ancestor to restyle it without specificity games; leave it unset for the default shown.

Layers: nz.components. Classes: .nz-command-menu-empty, .nz-command-menu-field, .nz-command-menu-footer, .nz-command-menu-group, .nz-command-menu-group-label, .nz-command-menu-hint, .nz-command-menu-icon, .nz-command-menu-input, .nz-command-menu-item, .nz-command-menu-kind, .nz-command-menu-label, .nz-command-menu-list, .nz-command-menu-popup, .nz-command-menu-search, .nz-dialog-popup.

AccessibilityCopy Anchor Link

These parts are interactive. Each gets the focus outline and touch-action rule from @nizivo/react/css/base.css (the nz.base layer), so the floor survives a restyle:

• command-menu-input: draws the focus outline itself on keyboard focus.
• command-menu-item: draws the focus outline when the engine reports keyboard focus, not on pointer hover.
• command-menu-trigger: draws the focus outline itself on keyboard focus.

KeyboardCopy Anchor Link

Source: React Aria Components 1.22.1 Autocomplete, SearchField and Menu (_engines/react-aria/command-menu.client.tsx) inside the Dialog; the shortcut from @nizivo/react/hotkeys. The browser lane (test/browser/command-menu.spec.tsx) checks ⌘K, the trigger, filtering, the arrow keys, Enter, Escape and the hotkeys policy.

FigmaCopy Anchor Link

Node ids from design/component-map.json, which nz gen writes from component.json. The links open the Nizivo Figma library, which may ask you to sign in.

• Canonical: Figma node 755:889
• Ghost masters: none