# Command palette

> Type to filter, arrow to move, Enter to run. Inline or as a ⌘K dialog.

Component · Pro · https://lodeui.com/components/command-palette

## When to use

- Power-user actions and site search behind ⌘K.
- Long action lists that benefit from type-to-filter.

## When not to use

- As the only way to reach an action: keep visible controls too.
- Choosing a form value: use a combobox.

## Installation

```bash
npx shadcn@latest add @lode/command-palette
```

Pro: needs a Lode API key and the `@lode` registry in components.json. See https://lodeui.com/docs/cli.

npm dependencies: motion, lucide-react

## Usage

```tsx title="example.tsx"
import * as React from "react";
import { useRouter } from "next/navigation";
import { CommandDialog, useCommandShortcut } from "@/components/ui/command-palette";

export function GlobalSearch() {
  const router = useRouter();
  const [open, setOpen] = React.useState(false);
  useCommandShortcut(() => setOpen((o) => !o));
  return (
    <CommandDialog
      open={open}
      onOpenChange={setOpen}
      groups={[{ heading: "Pages", items: [{ id: "/settings", label: "Settings", keywords: ["account"] }] }]}
      onSelect={(item) => router.push(item.id)}
    />
  );
}
```

## API reference

### CommandPalette

Input plus grouped results with fuzzy matching. Render inline, or use CommandDialog for a modal.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| groups | `{ heading: string; items: CommandItem[] }[]` | – | Items have id, label, description, icon, shortcut, keywords and onSelect. |
| onSelect | `(item: CommandItem) => void` | – | Called on Enter or click, after the item's own onSelect. |
| placeholder / emptyMessage | `string` | – | Input placeholder and no-results text. |
| toolbar | `ReactNode` | – | Controls under the input, e.g. filter chips. |
| emptyQueryGroups | `CommandGroup[]` | – | Shown first while the query is empty, e.g. recent items. |
| maxHeight | `number` | `340` | List height before it scrolls. |

### CommandDialog

The palette in a modal with scroll lock, Escape to close and focus return.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| open / onOpenChange | `boolean / (open: boolean) => void` | – | Controlled visibility. Accepts every CommandPalette prop too. |

### useCommandShortcut

Calls a function on ⌘K or Ctrl+K.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| onTrigger | `() => void` | – | Usually toggles the dialog. |
| key | `string` | `"k"` | Letter to listen for with ⌘ or Ctrl. |

## Keyboard interactions

| Keys | Action |
| --- | --- |
| ↑ / ↓ | Move the highlight |
| Ctrl+P / Ctrl+N | Same as up and down |
| Home / End | First or last result |
| Enter | Run the highlighted item |
| ⌘K / Ctrl+K | Toggle (with useCommandShortcut) |
| Esc | Close the dialog |

## Accessibility

- The input is a combobox controlling a listbox through aria-activedescendant.
- Matched text is underlined, not just colored.
- The dialog is aria-modal and returns focus to where it was opened from.

## Motion

- The highlight glides between rows (spring, 220ms).
- The list height animates as results filter.
- The dialog scales in from 96%.

## Responsive behavior

- The dialog is full-width with 16px gutters on phones, 576px max on desktop.
- The ⌘K hint hides below 640px.

## Performance

- Scoring runs on every keystroke over label, description and keywords; fine up to a few thousand items.
- Scrolling keeps the active row visible by moving only the list, never the page.

## Notes for AI

- Put synonyms in keywords instead of the label.
- Item ids must be unique across groups.

## Related

- [Combobox](https://lodeui.com/components/combobox) — Searchable select for one or many values, fully keyboard driven.
- [Dropdown menu](https://lodeui.com/components/dropdown-menu) — Actions, checkboxes and radio options in a springy menu with full keyboard support.
- [Dialog](https://lodeui.com/components/dialog) — A modal or side sheet with focus trap, scroll lock and focus return.
- [Input](https://lodeui.com/components/input) — Text, search, password and URL inputs with icons, clear button and a labelled Field wrapper.