# Command menu
> ⌘K / Ctrl+K command palette with grouped commands, fuzzy search and a springing pixel highlight; focus stays in it while open.
- React: `import { PxCommand } from "@/components/lumesec/px-command"`
- Collection: Pixel UI (https://elements.lumesec.ai/components/pixel-ui)
- Registry item: https://elements.lumesec.ai/r/px-command.json
- Page: https://elements.lumesec.ai/components/pixel-ui/command



Live preview: https://elements.lumesec.ai/view/px-command

Demo source:

```tsx
import { PxCommand, type PxCommandItem } from "@/components/lumesec/px-command";

const COMMANDS: PxCommandItem[] = [
  { group: "Actions", label: "New chat", shortcut: "N" },
  { group: "Actions", label: "New project", shortcut: "P" },
  { group: "Actions", label: "Upload a file", shortcut: "U" },
  { group: "Actions", label: "Invite a teammate", shortcut: "I" },
  { group: "Go to", label: "Projects", shortcut: "G P" },
  { group: "Go to", label: "Usage and billing", shortcut: "G B" },
  { group: "Go to", label: "Settings", shortcut: "G S" },
  { group: "Go to", label: "Connectors", shortcut: "G C" },
  { group: "Preferences", label: "Toggle dark mode", shortcut: "⇧ D" },
  { group: "Preferences", label: "Keyboard shortcuts", shortcut: "?" },
];

export default function PxCommandDemo() {
  return (
    <div className="w-full max-w-[400px] rounded-[14px] border border-border bg-card px-5 py-[18px] shadow-[0_14px_34px_-20px_rgb(0_0_0/0.4)]">
      <PxCommand hotkey items={COMMANDS} />
    </div>
  );
}
```

## Playground

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

## Installation

```bash
npx shadcn@latest add @lumesec/px-command
```

First time with the @lumesec registry? Register it once, or install by URL:

```bash
npx shadcn@latest registry add @lumesec=https://elements.lumesec.ai/r/{name}.json
npx shadcn@latest add https://elements.lumesec.ai/r/px-command.json
```

## Usage

React:

```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.

| Prop           | Type                            | Default | Description                                                                                                                                        |
| -------------- | ------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `open`         | `boolean`                       | —       | Controlled open state. Use with `onOpenChange`.                                                                                                    |
| `defaultOpen`  | `boolean`                       | `false` | Initial open state when uncontrolled.                                                                                                              |
| `items`        | `readonly PxCommandItem[]`      | —       | The commands, in display order: `{ label: string; group: string; shortcut?: string }`. Consecutive commands with the same `group` share a heading. |
| `hotkey`       | `boolean`                       | `false` | Ctrl+K or ⌘K anywhere on the page opens and closes the palette.                                                                                    |
| `onOpenChange` | `(open: boolean) => void`       | —       | Called when the palette opens or closes: the trigger, the hotkey, Escape, the backdrop or running a command.                                       |
| `onCommand`    | `(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](/docs/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.