Command menu · Pixel UI component

<PxCommand />· loading

Trypress Ctrl+K (⌘K on a Mac).

Playground

Change a prop and the component re-renders. Props marked remounts set an initial value, so the component starts over.

Loading <PxCommand />

Props

hotkeylive

defaultOpenremounts

React

<PxCommand
  items={[
    {
      group: "Actions",
      label: "New chat",
      shortcut: "N"
    },
    {
      group: "Actions",
      label: "New project",
      shortcut: "P"
    },
    {
      group: "Actions",
      label: "Upload a file",
      shortcut: "U"
    },
    {
      group: "Go to",
      label: "Projects",
      shortcut: "G P"
    },
    {
      group: "Go to",
      label: "Settings",
      shortcut: "G S"
    },
    {
      group: "Preferences",
      label: "Keyboard shortcuts",
      shortcut: "?"
    }
  ]}
/>

Installation

pnpm dlx shadcn@latest add @lumesec/px-command

First timeRegister the @lumesec registry once, or install by URL+

Adds @lumesec to your components.json:

pnpm dlx shadcn@latest registry add @lumesec=https://elements.lumesec.ai/r/{name}.json

Or skip the setup and install by URL:

npx shadcn@latest add https://elements.lumesec.ai/r/px-command.json

Usage

px-command-example.tsx

import { PxCommand } from "@/components/lumesec/px-command";

export function Example() {
  return (
    <PxCommand
      hotkey
      items={[
        { group: "Actions", label: "New chat", shortcut: "N" },
        { group: "Actions", label: "New project", shortcut: "P" },
        { group: "Go to", label: "Settings", shortcut: "G S" },
      ]}
      onCommand={(item) => console.log(item.label)}
    />
  );
}

Behaviour

A ⌘K / Ctrl+K palette with grouped commands, fuzzy search and a springing pixel highlight. It traps focus while open and returns it to the trigger on close.

API reference

Props

Also accepts every prop of <div> (React.ComponentProps<"div">), spread onto the root element.

openTypeboolean

Controlled open state. Use with onOpenChange.

defaultOpenTypebooleanDefaultfalse

Initial open state when uncontrolled.

itemsTypereadonly PxCommandItem[]

The commands, in display order: { label: string; group: string; shortcut?: string }. Consecutive commands with the same group share a heading.

hotkeyTypebooleanDefaultfalse

Ctrl+K or ⌘K anywhere on the page opens and closes the palette.

onOpenChangeType(open: boolean) => void

Called when the palette opens or closes: the trigger, the hotkey, Escape, the backdrop or running a command.

onCommandType(item: PxCommandItem) => void

Called with the command the user runs. The palette closes first.

Ref

ref points at the root HTMLDivElement.

Keyboard

Keys	Action
Ctrl+K / ⌘K	Open or close the palette (with `hotkey`).
ArrowDown / ArrowUp	Move the highlight, wrapping at the ends.
Enter	Run the highlighted command.
Escape	Close the palette.
Tab	Blocked, so focus stays in the search input.

Accessibility

The trigger is a native button with aria-haspopup="dialog".
The palette has role="dialog", aria-modal="true" and aria-label="Command menu". Opening focuses the input, and a press anywhere else in the palette hands focus back to it; closing returns focus to the trigger.
The input has role="combobox", aria-expanded="true", aria-controls, aria-autocomplete="list" and aria-activedescendant. Commands are role="option" items with aria-selected in a role="listbox" labelled "Commands".
A status line under the trigger is an aria-live="polite" region that reports the command that ran.
Reduced motion: the backdrop and dialog appear without fading or popping, the highlight jumps instead of springing and the status line swaps without rolling.

Theming

Styled with Tailwind classes on your shadcn theme tokens, so light and dark follow your theme. The accent comes from --lumesec. See Theming.

This component reads --lumesec, --card, --border, --foreground and --muted-foreground.

Notes

While the query is empty, commands appear in items order under their group headings; with a query, the best fuzzy matches come first and headings are hidden.
With hotkey, the trigger shows ⌘ K on Apple platforms and Ctrl K elsewhere (Ctrl K during server rendering), and the status line starts with "Press the shortcut anywhere on the page". Without hotkey both are left out.
The overlay is position: fixed inside the component, so an ancestor that creates a containing block for fixed-position descendants (for example through transform, filter or contain) changes what it covers. Clicking the backdrop closes the palette.
Every opening starts with an empty query and the first command highlighted.

<px-tabs>

Tabspx-tabs

<px-pagination>

Paginationpx-pagination

<px-nav>

Sidebar navpx-nav

<px-accordion>

Accordionpx-accordion

Related