Command

Preview

Use the tabs to compare the temporary Basic palette, inset Layer dialog, and inline Preview layout.

Design guidance

Use Command to find one action or saved prompt in a known set. Keep search text separate from the highlighted row. Arrow keys and pointer movement update the highlighted record; they do not run the action. Give each item an onClick callback that acts on that exact record. Base UI calls the same item callback for Enter.

The caller owns records, filtering, action results, and any dialog state. Insert exact prompt text into the current draft. Use an inline picker when search belongs to the current task. Use a dialog for temporary search. Keep disabled actions visible only when their context matters; disabled rows cannot be highlighted or activated.

Command.Shortcut displays a hint. It does not install a keyboard handler. Add a scoped handler when the caller wants a key to run an action.

Installation

npx shadcn@latest add https://ghost-ui.com/r/command.json

The examples also compose Button, Kbd, Tabs, and Textarea. Add those components when copying their examples.

Basic usage

123456789101112131415161718192021222324252627282930313233import { useState } from "react";
import { Search } from "lucide-react";
import { InputGroup } from "@/components/ui/input-group";
import { Command } from "@/components/ui/command";
import { Textarea } from "@/components/ui/textarea";

const prompts = [
  { id: "recap", title: "Meeting recap", content: "Start with the decision. List action items with an owner and due date." },
  { id: "weekly", title: "Weekly update", content: "Write a weekly update with progress, next steps, and blockers." },
];

export function PromptPicker() {
  const [draft, setDraft] = useState("");
  return <>
    <Command.Inline>
      <Command.Root items={prompts} itemToStringValue={(prompt) => prompt.title}>
        <Command.Search>
          <InputGroup.Addon><Search aria-hidden="true" /></InputGroup.Addon>
          <Command.Input aria-label="Search prompts" placeholder="Search prompts…" />
        </Command.Search>
        <Command.List>
          <Command.Collection>{(prompt) => (
            <Command.Item key={prompt.id} value={prompt} onClick={() => setDraft(prompt.content)}>
              <Command.ItemLabel>{prompt.title}</Command.ItemLabel>
            </Command.Item>
          )}</Command.Collection>
          <Command.Empty>No prompts match your search.</Command.Empty>
        </Command.List>
      </Command.Root>
    </Command.Inline>
    <Textarea aria-label="Draft text" value={draft} onChange={(event) => setDraft(event.target.value)} />
  </>;
}

Command.Input composes Autocomplete behavior with the canonical InputGroup control. The item callback receives the record directly, so two records can have the same title. For caller filtering, pass the filtered records as items with filter={null}, or provide filteredItems while preserving the original flat or grouped shape.

Structures

For a plain palette, omit Layout, Panel, and Preview. Use Group and GroupLabel only when the list needs categories. Dialog adds its focus lifecycle around the same search/list composition.

Examples

Basic dialog

Use Basic for a short list of prompts. The dialog has a hidden title, returns focus to its trigger, and inserts the chosen prompt into an editable draft.

Layer dialog

Use Layer when the palette needs an inset surface. The example opens both the 600px single-column list and the 880px split view with a 320px list panel.

Preview detail

Use Preview when the highlighted prompt needs a readable detail pane. Highlighting changes the preview. The explicit Use prompt button inserts that record into the editable draft.

Inline picker

Use an inline picker when search is part of the current task. Item activation inserts the exact record into the editable draft.

Groups and shortcut hints

Group related prompts and actions. Shortcut hints are visual only; the caller owns keyboard handling.

Scrollable list

Keep a long collection in its own scroll region so search stays visible.

No results

The collection has records, but the current query filters them all out. Edit the search to restore matching prompts.

Empty collection

Use this state when the caller has no prompt records yet. It differs from a query with no matches.

Disabled action

Show a disabled action when its context matters. It remains visible, is skipped by keyboard navigation, and cannot run.

API reference

Command.Root preserves Base UI's flat and grouped item inference. It renders no DOM. value and defaultValue are query strings, not selected record IDs. Root defaults are inline={true}, open={true}, autoHighlight="always", keepHighlight={true}, and submitOnItemClick={false}. Explicit values override these defaults.

Command.Item keeps Base UI item behavior and render/ref/state class support. Put the action on its onClick; do not infer a record from its display label. Arrow and pointer highlight events do not run the action. Native Enter uses the same item callback.