Command Primitive

Overview and decision boundary

Use Command for an accessible local action picker whose query, results, and selection events remain composable and consumer-owned.

Do not add hidden fuzzy ranking, remote fetching, route navigation, or global shortcut registration to Command.

Installation and imports

Install the editable registry source, or use the matching package entrypoint when the product keeps Nerio as a workspace dependency.

1pnpm dlx nerio add command-primitive23import { Kbd } from '@nerio-ui/ui';4import { Command, CommandEmpty, CommandInput, CommandItem, CommandList } from '@nerio-ui/ui/client';

Usage

1<Command items={items} filter={false} query={query} onQueryChange={setQuery}>...</Command>

1<Popover trigger="Open commands">2  <Command>...</Command>3</Popover>

1<Dialog trigger="Open dialog" title="Workspace commands">2  <Command>...</Command>3</Dialog>

1<Sheet>2  <SheetTrigger render={<Button>Open sheet</Button>} />3  <SheetContent><Command>...</Command></SheetContent>4</Sheet>

1import { Kbd } from '@nerio-ui/ui';2import { Command, CommandEmpty, CommandInput, CommandItem, CommandList } from '@nerio-ui/ui/client';34const items = [{ value: "settings", label: "Workspace settings", keywords: ["preferences"] }];56<Command items={items}>7  <CommandInput aria-label="Workspace commands" placeholder="Search commands" />8  <CommandEmpty>No matching commands.</CommandEmpty>9  <CommandList>10    {(item) => (11      <CommandItem key={item.value} value={item.value} shortcut={<Kbd aria-hidden>⌘,</Kbd>} onSelect={(value, event) => runCommand(value, event)}>12        {item.label}13      </CommandItem>14    )}15  </CommandList>16</Command>

Variants

1<Command items={groupedItems}>...</Command>

Anatomy

States

1<Command defaultQuery="no-match" items={items}>...</Command>

Motion

• Command itself does not animate active-item movement or query updates.
• Popover, Dialog, and Sheet retain their own reduced-motion-aware overlay behavior.

Accessibility

• Uses the Base UI Autocomplete combobox and listbox interaction model while keeping DOM focus on CommandInput through aria-activedescendant.
• CommandInput requires a visible label, aria-label, or aria-labelledby; placeholder text is not an accessible name.
• Arrow keys navigate enabled items, disabled items are skipped, Enter selects the active item, and Escape bubbles to enclosing Popover, Dialog, or Sheet dismissal behavior.
• Home and End preserve native input editing because virtual focus remains on the query field.
• Base UI suppresses Enter selection during IME composition and supports pointer highlighting and selection without moving DOM focus into items.
• Selection writes only the visible item label into controlled or uncontrolled query and form values; keywords and stable values are matching-only text.
• CommandItem leading content owns its accessibility semantics; decorative Nerio Icons remain hidden through their own default contract.
• CommandEmpty and CommandLoading use dedicated polite Base UI status regions and are not arbitrary children of the listbox.
• RTL, long localized labels, compact density, reduced motion, and forced colors are supported through semantics and tokens.
• Fetching, ranking, routing, permissions, analytics, history, global shortcuts, and complete command-palette workflows remain consumer or Pro responsibilities.

API

Implementation contract

Styling contract

Design notes

• Command is not GlobalSearch, EntitySearch, Documentation Search, or a complete Command Palette.
• Fetching, ranking, routing, permissions, analytics, history, recent items, and global shortcuts stay outside Core.
• Use consumer state to replace items and toggle CommandLoading for asynchronous results.
• Leading content is general React content and owns its semantics; use decorative Nerio Icons when no accessible meaning is needed.

Do / do not

Related components

Tokens

These are the primary customization points. Override semantic or component tokens instead of changing component source.