React

React Integration

@cmd-kit/react ships a ready-to-use CommandPalette component plus the useCommandPalette hook for custom integrations.

Install

npm install @cmd-kit/react

Basic usage

Start with one section and one item. That is enough to confirm the integration before you spend time on styling.

import { CommandPalette } from "@cmd-kit/react";

const sections = [
  {
    id: "navigation",
    title: "Navigation",
    items: [
      { id: "dashboard", title: "Dashboard", href: "/dashboard" }
    ]
  }
];

export function Example() {
  return <CommandPalette sections={sections} title="Project commands" />;
}

Core props

sections or items: static data
source: computed or async commands
messages: placeholder, empty state, close label
theme: single mode or dual mode ({ light, dark }) tokens
classNames and renderers: visual and structural overrides
recents: recent commands section (off by default)
reducedMotion: disable hover and motion animations
open, defaultOpen, onOpenChange: controlled state

Icons and custom item layout

Use renderItem when you want to control the item row completely, including icons, spacing, and extra metadata.

<CommandPalette
  sections={sections}
  renderItem={(item, active) => (
    <div className={active ? "palette-row is-active" : "palette-row"}>
      <MyIcon name={item.id} />
      <div className="palette-row-copy">
        <strong>{item.title}</strong>
        {item.subtitle ? <span>{item.subtitle}</span> : null}
      </div>
    </div>
  )}
  title="Project commands"
/>

Customization example

<CommandPalette
  classNames={{
    dialog: "palette-shell",
    item: "palette-item"
  }}
  messages={{
    searchPlaceholder: "Search actions",
    noResults: "No commands match your query."
  }}
  theme={{
    light: {
      accentColor: "#0fa6d8",
      backgroundColor: "#ffffff",
      textColor: "#0e1720"
    },
    dark: {
      accentColor: "#12b5e5",
      backgroundColor: "#0f1720",
      textColor: "#f5fbff"
    }
  }}
  sections={sections}
  title="Workspace commands"
/>

Async source

<CommandPalette
  source={async () => {
    const response = await fetch("/api/commands");
    return response.json();
  }}
  recents={{ limit: 6, sectionTitle: "Recent" }}
  title="Workspace commands"
/>

Add a new command

Add a new option by pushing a new item into your section. shortcut is optional: use it when needed or omit it for click/Enter only.

const sections = [
  {
    id: "navigation",
    title: "Navigation",
    items: [
      { id: "dashboard", title: "Dashboard", href: "/dashboard" },
      { id: "billing", title: "Billing", href: "/billing", shortcut: "mod+b" },
      { id: "support", title: "Support", href: "/support" }
    ]
  }
];

Recent commands

recents is optional and disabled by default. Enable it with recents={true} or configure it with recents={{ limit: 6, sectionTitle: 'Recent' }}. Disable it with recents={false}.

<CommandPalette
  sections={sections}
  recents={false}
  title="Workspace commands"
/>

FAQ

Should I use CommandPalette or useCommandPalette?

Start with CommandPalette. Use useCommandPalette when you need to orchestrate state and rendering yourself.

How do I avoid shortcut conflicts with my app?

Override shortcut and pick a combination that does not collide with existing editor, search, or browser shortcuts.

Can I control open state from React state?

Yes. Use open and onOpenChange for controlled mode, or defaultOpen for uncontrolled mode.

How do I disable recent commands in React?

Keep recents undefined (default off) or pass recents={false}.

How should I load commands from an API?

Use source and return the same command shape (items and/or sections) that static configuration uses.

What is the best way to customize row UI?

Use renderItem for full row control, or renderers for targeted overrides like title, section title, and empty state.