Command

Playground

Installation

pnpm add @tessinaui/ui

Usage

import {
  Command,
  useCommandShortcut,
} from "@tessinaui/ui";

Inline command palette

Embed the palette directly in the page. The list is always visible — typing into the input filters items live.

<Command.Root size="md" rounded="md">
  <Command.Input placeholder="Type a command or search…" shortcut="⌘K" />
  <Command.List>
    <Command.Empty />
    <Command.Group heading="Suggestions">
      <Command.Item value="dashboard" leadingIcon={<LayoutDashboard />}>
        <Command.ItemTitle>Dashboard</Command.ItemTitle>
        <Command.Shortcut>⌘D</Command.Shortcut>
      </Command.Item>
      <Command.Item value="settings" leadingIcon={<Settings />}>
        <Command.ItemTitle>Settings</Command.ItemTitle>
      </Command.Item>
    </Command.Group>
  </Command.List>
</Command.Root>

Modal command palette

Wrap the same content in Command.Dialog to make a ⌘K overlay. Pair with useCommandShortcut("k", …) for a global keyboard trigger. The dialog stays a centered card at every size; below md it sits just under the safe area and caps at min(45dvh, 24rem) so the input, the results and the footer all stay above a virtual keyboard (mobilePresentation="fullscreen" opts into the takeover instead).

function App() {
  const [open, setOpen] = useState(false);
  useCommandShortcut("k", () => setOpen((o) => !o));

  return (
    <Command.Dialog open={open} onOpenChange={setOpen}>
      <Command.Input placeholder="Search…" />
      <Command.List>
        <Command.Empty />
        <Command.Group heading="Actions">
          <Command.Item value="new-file" onSelect={() => createFile()}>
            <Command.ItemTitle>New file</Command.ItemTitle>
            <Command.Shortcut>⌘N</Command.Shortcut>
          </Command.Item>
        </Command.Group>
      </Command.List>
      <Command.Footer>
        <Command.FooterHint shortcut="enter">To select</Command.FooterHint>
        <Command.FooterHint shortcut="arrows">To navigate</Command.FooterHint>
        <Command.FooterHint shortcut="escape" appearance="ghost">To close</Command.FooterHint>
      </Command.Footer>
    </Command.Dialog>
  );
}

Items with rich content

Items can hold a title, optional description, inline trailing metadata, a breadcrumb path, and a trailing shortcut. Command.HighlightMatch emphasises the query inside any text.

<Command.Item value="settings-team" keywords={["prefs"]} leadingIcon={<Users />}>
  <Command.ItemTitle>
    <Command.HighlightMatch>Team settings</Command.HighlightMatch>
  </Command.ItemTitle>
  <Command.ItemDescription>Invite or remove members</Command.ItemDescription>
  <Command.ItemMeta>workspace</Command.ItemMeta>
  <Command.Shortcut>⌘T</Command.Shortcut>
</Command.Item>

<Command.Item value="docs-deep-link">
  <Command.Crumbs crumbs={["Components", "Form", "Field"]} />
</Command.Item>

Examples

Default

An inline command palette with grouped suggestions, icons, and shortcuts. With text in the field, Esc clears it (with it empty, a wrapping dialog's Esc dismisses).

Modal dialog

Command.Trigger + useCommandShortcut + a live result count in the footer.

Mobile presentation

mobilePresentation="fullscreen" opts below md into the takeover every surveyed mobile system ships, with a Cancel button composed from Command.Close in the input's trailing slot. It is opt-in rather than the default because a full-height sheet pins its footer to the layout viewport's bottom edge — and on iOS the keyboard covers that edge without shrinking dvh, so footer hints go out of view. Keep the dismiss affordance in the input row when you use it.

Anchored

The palette hanging off a page control via the house Popover — Command.Root is position-agnostic.

Scope toolbar

Command.Toolbar hosts a result-type switcher between the input and the results. It renders outside the listbox, so interactive children are legal.

Match highlighting

Command.HighlightMatch wraps query occurrences in a de-yellowed <mark>.

Async search

External filtering (disableFiltering), the input's loading spinner, skeleton result rows, and Command.Error with a forceMount retry item — type fail to see the error path.

Actionable empty state

The default Command.Empty copy echoes the query. Recovery actions are pinned options (forceMount items) — a button inside the listbox would be an aria-required-children violation.

Recents chips

Command.Chips with per-chip remove (Delete/Backspace on the focused chip) and a legal "Clear all" action — the row is one Tab stop with arrow-key navigation.

Filtering

keywords aliases, value inference from the visible title, and a custom filter.

Pinned AI row

A forceMount item stays visible under every query — the ask-AI pattern.

Nested pages

The cmdk-endorsed pages recipe on plain composition: a page stack in consumer state, Backspace on an empty input pops, the trail renders as chips.

Rich content layout

Cards, app icons and sections compose inside Command.Panel — a scroll column with no listbox role, so its buttons are valid and Tab-reachable. The sidebar is a real tablist (one Tab stop, Up/Down arrows).

Rich items

Items with descriptions, avatars, metadata, and breadcrumb paths.

Sizes

Five sizes from xs to xl, each with proportional padding, type, and icons. On phones the input floors at 16px text (iOS zoom) and rows at 44px.

Rounded

Six corner steps from none to full. The scale follows the §2 panel ladder — full caps at 24px, the panel maximum.

Intent

A semantic accent on the container border — none, error, warning, success, or info.

States

Empty (query echo), loading (spinner and skeleton variants), error, and the whole-component skeleton.

API Reference

Command.Root / Command.Dialog props

Both accept the same visual props. Command.Root renders inline; Command.Dialog renders inside a Base UI Dialog with backdrop and focus trap.

Forwarding: aria-* land on the input (the element with the combobox role); data-*, ids and handlers land on the wrapper (Root) / dialog popup (Dialog). Both modes split identically.

Command.Dialog additional props

Command.Input props

With text in the field, Esc clears it and stops; with it already empty the event passes through, so a wrapping Dialog can dismiss — the APG two-stage contract.

Command.Toolbar

A padded, horizontally scrolling control row between the input and the results. Renders outside the listbox, so interactive children are legal — compose SegmentedControl, Select size="xs", Chip filters. No props beyond standard div attributes.

Give the control you compose the palette's own rounded value. The radius cascade crosses composition boundaries: a rounded="full" pill switcher inside a rounded="md" panel reads as a foreign part.

Command.Item props

Command.ItemMeta

Muted inline metadata at the trailing edge of a row — a suffix like "— Build", a domain, an author, a date. A sibling of the title column (like Command.Shortcut), not stacked under it. It joins the option's accessible name, so keep it short; never interactive.

Command.HighlightMatch props

Command.Group props

Put actions in an item, not in the heading row. Command.List is the combobox listbox, and ARIA gives role="listbox" a closed set of permitted children: option and group. A control in the heading row is therefore an aria-required-children failure at critical severity, and no wrapper rescues it — role="presentation" is ignored on a focusable element, and aria-hidden would only trade the rule for aria-hidden-focus.

Render a group action as a Command.Item. That is a real option, so it is an allowed child and it is reachable with the arrow keys — a button in the heading row is Tab-only, so reaching it means leaving the combobox. Passing a focusable node to headingTrailing warns in development.

<Command.Group heading="Recent searches" headingTrailing={<span>3</span>}>
  <Command.Item value="darlene">…</Command.Item>
  <Command.Item value="clear-recent" leadingIcon={<Eraser />} onSelect={clear}>
    <Command.ItemTitle>Clear recent searches</Command.ItemTitle>
  </Command.Item>
</Command.Group>

Command.Crumbs props

Command.Empty props

Non-interactive (it lives in the listbox) — put recovery actions in a forceMount Command.Item, Command.Chips, or Command.Footer.

Command.Loading props

Command.Error props

Command.Chips / Command.ChipItem props

The row is one Tab stop; Left/Right arrows move between chips.

Command.Body / Command.Sidebar props

The sidebar is a role="tablist" with the full keyboard contract: one Tab stop, Up/Down arrows move, Home/End jump, Enter/Space activates.

Command.Panel props

The rich-content column: scrolls and pads like Command.List, carries no listbox role, so cards, chips and app icons are legal, Tab-reachable children. Use Command.List for options, Command.Panel for content.

Command.Section props

Auto-hides when filtering removes every Command.Item, Command.ChipItem, or Command.Card descendant.

Command.Grid / Command.Card props

Command.IconRow / Command.AppIcon props

useCommandShortcut(key, onTrigger, options?)

Hook for binding a global keyboard trigger.

Unmodified and shift-only bindings are suppressed while typing in an input, textarea, select, or contenteditable; held-key auto-repeat and IME composition are ignored for every modifier.

Rich content layouts

For Mobbin / Linear / Raycast-style palettes, compose on top of the core API — with interactive rich content in Command.Panel, never Command.List (the listbox may own only options and groups):

• Command.Chips + Command.ChipItem — horizontal pill row (recents, filters) with a legal action slot
• Command.Toolbar — scope tabs / filter dropdowns / mode toggles
• Command.Body + Command.Sidebar + Command.SidebarItem — two-column layout with a real-tablist nav rail
• Command.Panel — the scrolling content column for anything interactive
• Command.Section — heading wrapper; auto-hides when its filterable children all filter out
• Command.Grid + Command.Card — thumbnail card grid (filter-aware via value/keywords)
• Command.IconRow + Command.AppIcon — horizontal app logo strip

<Command.Dialog>
  <Command.Input placeholder="Apps, Screens, UI Elements…" />
  <Command.Chips action={<Button variant="ghost" size="xs">Clear all</Button>}>
    <Command.ChipItem leadingIcon={<Search />} value="transactions">transactions</Command.ChipItem>
  </Command.Chips>
  <Command.Body>
    <Command.Sidebar value={view} onValueChange={setView}>
      <Command.SidebarItem value="trending" leadingIcon={<TrendingUp />}>Trending</Command.SidebarItem>
      <Command.SidebarItem value="screens"  leadingIcon={<Smartphone />}>Screens</Command.SidebarItem>
    </Command.Sidebar>
    <Command.Panel>
      <Command.IconRow>
        <Command.AppIcon src="/duolingo.png" label="Duolingo" />
      </Command.IconRow>
      <Command.Section heading="Screens">
        <Command.Grid columns={3}>
          <Command.Card value="signup" title="Signup" image="/signup.png" />
        </Command.Grid>
      </Command.Section>
    </Command.Panel>
  </Command.Body>
</Command.Dialog>

Accessibility

• The input is the combobox: aria-expanded="true", aria-controls → the list, aria-autocomplete="list" (the APG trio for an always-open inline combobox). Arrow keys move the highlight via aria-activedescendant, Enter selects, typing filters.
• Command.List is role="listbox" and owns only options and groups. Everything else the palette renders there — Empty, Error, the Loading row, separators — is presentational; interactive rich content goes in Command.Panel.
• Async announcements come from a root-owned, always-mounted role="status" region outside the listbox: Command.Loading/Command.Error portal their labels into it, and the palette announces "N results" 150ms after each query settles.
• Esc clears a filled input first; a second Esc (field empty) reaches the Dialog and closes it.
• The dialog traps focus (@base-ui/react/dialog) and stays a centered card below md, offset by the top safe area and capped so nothing hides behind a virtual keyboard; initialFocus opts out of input autofocus where a keyboard would occlude content.
• Chips rows and the sidebar are single Tab stops with arrow-key roving; a chip with onRemove deletes with Delete/Backspace; the sidebar is a real vertical tablist.
• Phone floors: input text ≥16px (no iOS zoom-on-focus), rows/chips/sidebar items/app icons ≥44px targets, the clear button's hit area is extended to 44px.