Key hints

Shortcuts

Reset after a choice

Command Palette

New

A search field over your commands, with nested pages that slide in and a highlight that glides between rows.

Install it in one line

Available in v1.9.0

npx devignerui add command-palette

Writes components/ui/command-palette.tsx and lists what it needs.

First time here

npx devignerui init

Or by hand

Needs React 18 or 19 and Tailwind CSS v4.
Install the dependencies.
npm i cn motion @devigner-ui/icons devignerui
Paste the source from into components/ui/command-palette.tsx.

Some of these designs take cues from interfaces we've admired around the web. If one started as your idea and you'd like credit, message us on X @devignerui or in the Discord and we'll add it.

Usage

import { IconDiamondDivided, IconMoon, IconSunLongRays } from "@devigner-ui/icons";
import {
  CommandPalette,
  type CommandPaletteItem,
} from "@/components/ui/command-palette";

const items: CommandPaletteItem[] = [
  {
    label: "Browse components",
    group: "Suggestions",
    icon: <IconDiamondDivided />,
    shortcut: ["G", "C"],
  },
  {
    label: "Change theme",
    group: "Settings",
    icon: <IconSunLongRays />,
    items: [
      { label: "Light", icon: <IconSunLongRays /> },
      { label: "Dark", icon: <IconMoon />, keywords: ["night"] },
    ],
  },
];

export function Example() {
  return (
    <CommandPalette
      items={items}
      onSelect={(item) => console.log(item.label)}
    />
  );
}

Custom composition

<CommandPalette items={commands} autoFocus hints={false} onSelect={() => setOpen(false)} messages={{ placeholder: "Type a command" }} />

Open it with Cmd+K

A native dialog that opens on Cmd+K or Ctrl+K, focuses the field and closes after a command runs.

import { useEffect, useRef } from "react";
import { CommandPalette, type CommandPaletteItem } from "@/components/ui/command-palette";

export function CommandMenu({ items }: { items: CommandPaletteItem[] }) {
  const dialog = useRef<HTMLDialogElement>(null);
  useEffect(() => {
    const onKey = (e: KeyboardEvent) => {
      if (e.key.toLowerCase() === "k" && (e.metaKey || e.ctrlKey)) {
        e.preventDefault();
        dialog.current?.showModal();
      }
    };
    window.addEventListener("keydown", onKey);
    return () => window.removeEventListener("keydown", onKey);
  }, []);
  return (
    <dialog ref={dialog} className="m-auto bg-transparent p-0 backdrop:bg-black/40">
      <CommandPalette items={items} autoFocus onSelect={() => dialog.current?.close()} />
    </dialog>
  );
}

Nested pages with groups and shortcuts

Rows sharing a group sit under one heading; a row with items opens a page.

import { CommandPalette, type CommandPaletteItem } from "@/components/ui/command-palette";

const items: CommandPaletteItem[] = [
  { label: "New file", group: "Files", shortcut: ["Ctrl", "N"], onSelect: () => console.log("new") },
  { label: "Open recent", group: "Files", keywords: ["history"], onSelect: () => console.log("recent") },
  {
    label: "Change theme",
    group: "Settings",
    items: [
      { label: "Light", onSelect: () => console.log("light") },
      { label: "Dark", keywords: ["night"], onSelect: () => console.log("dark") },
    ],
  },
];

export function Example() {
  return <CommandPalette items={items} />;
}

Every prop

items-

CommandPaletteItem[]

The rows: { label, id?, icon?, description?, action?, group?, keywords?, shortcut?, items?, onSelect?, disabled? }. A row with items opens a page of its own; description adds a muted second line, and action is the word shown on the active row.

onSelect-

(item) => void

Called for every chosen row that is not a page, after the row's own onSelect.

query-

string

Controlled search text. Pass with onQueryChange.

defaultQuery""

string

Search text on first render when uncontrolled.

onQueryChange-

(query: string) => void

Called as the search text changes.

path-

number[]

Controlled page as an index path: [] is the top, [3] the page row 3 opened. Pass with onPathChange.

defaultPath[]

number[]

Page on first render when uncontrolled.

onPathChange-

(path: number[]) => void

Called when a page opens or closes.

resetOnSelecttrue

boolean

After a row runs, clears the search and goes back to the top page.

hintstrue

boolean

Shows the Move, Open and Back key hints under the list.

labelCommand palette

string

Accessible name of the search field.

autoFocusfalse

boolean

Focuses the search field on mount, for a palette that opens in a dialog.

onEscape-

() => void

Called on an Escape with no search to clear and no page to leave, and shows an Esc cap in the field. Close a dialog from here.

groupActions-

Record<string, CommandPaletteGroupAction>

A button at the end of a group heading, keyed by group name: { label, onSelect }, such as Clear on a Recent group.

messages-

Partial<CommandPaletteMessages>

Replaces any built-in string: the placeholder, the empty states, the back button name and the hints.

classNames-

CommandPaletteClassNames

Slot classes: root, field, list, item, indicator (the gliding highlight) and footer.

How to use it

The live demo is a palette with suggestions and settings. Type to filter every page at once, move with the arrow keys, and open Change theme to see the next page slide in with its name as a crumb in the field.

When to use it

A Cmd+K or Ctrl+K launcher for an app or docs site: jump to pages, run actions, change settings.
Long command lists that benefit from search, grouped into sections, with deeper pages for choices like theme or language.

When to reach for something else

Picking one value for a form field. Use a select or combobox, which keeps the choice visible in the field.
Primary navigation people need to see without typing. Use visible links or tabs.

Keyboard

Up / Down arrows: Move the highlight, skipping disabled rows, looping at the ends.
Enter: Runs the highlighted row, or opens its page.
Backspace: On an empty field, goes back one page.
Escape: Clears the search, then goes back a page. On the top page with an empty field it calls onEscape, so a dialog around the palette can close.

Accessibility

The field is a combobox controlling a listbox, and the highlighted row is announced through aria-activedescendant, so focus never leaves the field.
Sections are groups named by their heading, rows with a page carry aria-haspopup, and disabled rows carry aria-disabled.
An empty search is a status message that names the query.
The crumb in the field is a button named "Back from <page>" by default.
Honors prefers-reduced-motion and an ancestor <MotionConfig reducedMotion="always">, so an in-app motion switch works too.

Theming

classNames targets root, field, list, item, indicator and footer.
Colors come from shadcn tokens: the highlight is foreground at 4.5% (7% in dark), matches and the crumb are primary. Idle rows are muted-foreground and the active one foreground. The surface is var(--panel) when your app defines it and background otherwise, with a 4% foreground rim and a layered shadow. Key caps and icon tiles are inset wells on background/40.
messages replaces the placeholder, both empty states, the crumb's name, the hint labels and the default action word.
shortcut shows key caps at the end of a row. They are display only; bind the keys yourself.
The active row shows its action word in primary at the end (messages.run, Run, when the item sets none). A row with a shortcut keeps its keys instead.
Group headings and their actions are set in the mono font, rows at 13px; the icon darkens on the active row.

Edge cases

A search covers the current page and every page under it. Results show the pages they sit in, and drop section headings so the best match comes first.
Choosing a row runs its onSelect, then the palette's onSelect, then returns to the top page with an empty field. Set resetOnSelect to false to stay put.
A row with both items and onSelect opens its page; onSelect is not called.
The search matches a row's description as well as its label and keywords.
The pointer lights the nearest row, so a heading or a gap between rows never drops the highlight. Each time the pointer enters the list, the highlight fades in under it rather than sliding over from the row the keys left it on.
A group action button keeps focus in the field when clicked, so the arrow keys still work after it runs.
The list scrolls past 384px, keeping the highlighted row in view without scrolling the page.
The palette is inline. Put it in your own dialog or popover to open it with Cmd+K, as in the recipe.

Troubleshooting

Escape closes my dialog while there is still text in the field.

It shouldn't: the palette stops Escape while it has a search or a page to undo. If your dialog listens on window in the capture phase, listen in the bubble phase instead.

The palette goes back to the top after every choice.

That is resetOnSelect, on by default. Pass resetOnSelect={false} to keep the page and search.

The component renders with no background or the wrong colors.

Colors use the standard shadcn/ui tokens only (background, foreground, primary, secondary, muted, accent, border, input, ring, destructive), so a project set up with shadcn/ui needs nothing extra and the component follows its theme, dark mode included. Without shadcn/ui, define those CSS variables for :root and .dark and map them in your Tailwind v4 @theme, or run npx shadcn init.

Stuck on something else? Ask in the Discord.