# Command palette (goodtabs UI)

A Cmd K dialog with search, grouped items with icons and kbd hints, and an empty state.

## Install

```bash
npx shadcn@latest add https://ui.goodtabs.co/r/command-palette.json
```

Or, with the @goodtabs namespace configured in components.json: `npx shadcn@latest add @goodtabs/command-palette`

## Usage

```tsx
import { CommandPalette, useCommandPalette } from "@/components/ui/command-palette"

const { open, setOpen } = useCommandPalette()

<CommandPalette
  open={open}
  onOpenChange={setOpen}
  groups={[{ heading: "Pages", items: [{ id: "docs", label: "Docs", shortcut: "g d" }] }]}
  onSelect={(id) => router.push(`/${id}`)}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| groups | `{ heading: string; items: { id: string; label: string; icon?: ComponentType; shortcut?: string; hint?: string }[] }[]` |  | The groups, in order. shortcut is a combination like "mod+k"; hint is short muted text. |
| open | `boolean` |  | Whether the dialog is shown. Controlled, pair with onOpenChange. |
| onOpenChange | `(open: boolean) => void` |  | Called when the dialog asks to open or close, including Escape and a click outside. |
| onSelect | `(id: string) => void` |  | Called with the id of the chosen item after the dialog closes. |
| placeholder | `string` | `"Type a command or search"` | Placeholder of the search input. |
| emptyText | `string` | `"No results."` | Shown when the search matches nothing. |
| title | `string` | `"Command palette"` | Accessible name of the dialog. |
| autoScroll | `boolean` | `true` | On CommandPaletteMenu. Off stops cmdk scrolling the selected row into view on mount, for inline menus on long pages. |

## When to use

- As the one place to jump to any page or run any action with the keyboard
- In apps and docs sites where people already reach for Cmd K
- When navigation has outgrown a menu but a full search page is too much

## When not to use

- For a short list of actions on one element, use a dropdown menu
- For picking a value in a form, use a select or a combobox
- On marketing pages with a handful of links

## Notes for agents

- useCommandPalette() holds open state and binds mod+k on the document; pass its open and setOpen to CommandPalette
- Ids must be unique across all groups: cmdk matches the search against the id and the label
- CommandPaletteMenu is the list without the dialog, for an inline or always-open menu; ShortcutKeys renders any combination as kbd
- The parent must be a client component because onSelect and onOpenChange are functions
- An inline CommandPaletteMenu far down a page makes the page jump on load unless autoScroll is false; the dialog form never needs it

Docs: https://ui.goodtabs.co/components/command-palette