How to add a Cmd+K command palette to a React app

A command palette lets people jump anywhere or run any action without reaching for the mouse. Linear, Vercel and GitHub all have one, and users now expect Cmd+K to do something. This tutorial uses ReactFrame's free Command Palette.

1. Install

npx shadcn@latest add @reactframe/command-palette

2. Describe your commands

Each command has an id, a label and usually an onSelect. group puts it under a heading, shortcut shows the keys next to it, and keywords are extra words it can be found by.

"use client";

import { useRouter } from "next/navigation";
import { CommandPalette, CommandGlyph, type CommandItem } from "@/components/command-palette";

export function AppCommands() {
  const router = useRouter();

  const items: CommandItem[] = [
    { id: "dashboard", label: "Go to dashboard", group: "Navigate", onSelect: () => router.push("/dashboard") },
    { id: "billing", label: "Billing", group: "Navigate", keywords: ["invoice", "plan", "payment"], onSelect: () => router.push("/settings/billing") },
    { id: "new-project", label: "New project", group: "Actions", icon: <CommandGlyph name="plus" />, shortcut: ["N"], onSelect: () => router.push("/projects/new") },
    { id: "theme", label: "Toggle dark mode", group: "Settings", icon: <CommandGlyph name="moon" />, keywords: ["theme", "appearance"], onSelect: () => document.documentElement.classList.toggle("dark") },
  ];

  return <CommandPalette items={items} placeholder="Search or jump to..." />;
}

Render <AppCommands /> once, in your app layout. Nothing else is needed for the shortcut: the palette listens for Cmd+K (Mac) and Ctrl+K (Windows, Linux) on its own.

3. Open it from a button too

Not everyone knows the shortcut. Control it with open and onOpenChange and add a visible trigger:

const [open, setOpen] = React.useState(false);

<button onClick={() => setOpen(true)} className="rounded-lg border px-3 py-1.5 text-sm text-neutral-500">
  Search... <kbd className="ml-6 text-xs">⌘K</kbd>
</button>
<CommandPalette open={open} onOpenChange={setOpen} items={items} />

Keyboard behaviour

• Cmd/Ctrl+K opens and closes it. Change the letter with hotkey="p", or pass hotkey={false} to turn the shortcut off.
• Arrow keys move through the results, Enter runs the highlighted one, Escape closes.
• Search is fuzzy and matches keywords as well as labels, so "invoice" finds "Billing".
• The palette closes after a command runs; set closeOnSelect={false} for commands that should keep it open.

Tips

• Name commands as actions ("Invite teammate", "Go to settings"), not as page titles; that's what people type.
• Add synonyms as keywords. People search for "logout", "sign out" and "log off".
• Don't list everything. 20 useful commands beat 200; add dynamic results (projects, customers) only when the query is typed.
• Use theme="light" to match a light app.