Command Menu React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Command Menu is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import CommandMenu from @/components/ui/command-menu.

"use client"

import { FilePlus2, Moon, Sun, UserPlus } from "lucide-react"
import { useTheme } from "next-themes"
import { CommandMenu, CommandMenuTrigger, commandItemsFromNav, type CommandGroup } from "@/components/ui/command-menu"
import type { NavItem } from "@/lib/navigation"

const nav: NavItem[] = [
  { label: "Clients", href: "/clients" },
  { label: "Invoices", href: "/invoices", items: [{ label: "Overdue", href: "/invoices/overdue" }] },
]

export function AppCommandMenu() {
  const { setTheme } = useTheme()
  const groups: CommandGroup[] = [
    { label: "Go to", items: commandItemsFromNav(nav) },
    {
      label: "Actions",
      items: [
        { id: "new-client", label: "New client", icon: <UserPlus />, href: "/clients/new" },
        { id: "new-invoice", label: "New invoice", icon: <FilePlus2 />, shortcut: "shift+mod+f", href: "/invoices/new" },
        { id: "theme", label: "Theme…", icon: <Moon />, page: "theme" },
      ],
    },
  ]
  return (
    <CommandMenu
      groups={groups}
      pages={[
        {
          id: "theme",
          title: "Theme",
          groups: [
            {
              items: [
                { id: "light", label: "Light", icon: <Sun />, onSelect: () => setTheme("light") },
                { id: "dark", label: "Dark", icon: <Moon />, onSelect: () => setTheme("dark") },
              ],
            },
          ],
        },
      ]}
      loadItems={async (query, { signal }) => {
        const res = await fetch(`/api/search?q=${encodeURIComponent(query)}`, { signal })
        const clients: { id: string; name: string; city: string }[] = await res.json()
        return [{ label: "Clients", items: clients.map((c) => ({ id: c.id, label: c.name, description: c.city, href: `/clients/${c.id}` })) }]
      }}
      placeholder="Type a command or search…"
      trigger={<CommandMenuTrigger placeholder="Search or jump to…" />}
    />
  )
}

Props

• groups
  CommandGroup[]

  The root page: groups of { id?, label?, items }. An item is { id, label, icon?, description?, badge?, keywords?, shortcut?, href?, external?, page?, onSelect?, tone?, disabled?, closeOnSelect? }. Build a “Go to” group from your navigation with commandItemsFromNav (see Parts).

• pages
  CommandPage[]

  Pages pushed by items with page: { id, title, placeholder?, groups?, loadItems? }. A page's own groups and loader replace the root ones.

• trigger
  ReactNode

  Rendered asChild as the trigger. CommandMenuTrigger (see Parts) is the ready-made search-field button.

• loadItems
  (query: string, context: { signal: AbortSignal; page: string | null }) => Promise<CommandGroup[]>

  Async results shown after the static groups (clients, invoices). Debounced, and the previous request is aborted. On the root page it runs once the query is not empty; errors show a row with Try again.

• debouncedefault 200
  number

  Milliseconds of quiet typing before loadItems runs.

• defaultOpendefault false
  boolean

  Starts open. Use open and onOpenChange to control it.

• open
  boolean

  Controlled open state; pair it with onOpenChange.

• onOpenChange
  (open: boolean) => void

  Fires when the menu opens or closes.

• page
  string | null

  The open page (null is the root), for opening straight into one. Pair it with onPageChange; defaultPage for uncontrolled.

• defaultPagedefault ""
  string | null

  The page it opens on while uncontrolled (a page id; empty is the root, an unknown id is ignored). It returns there every time it reopens. The demo has the tema and limba pages.

• onPageChange
  (page: string | null) => void

  Fires when a page is pushed or popped.

• query
  string

  Controlled search text; defaultQuery and onQueryChange complete the pair.

• defaultQuerydefault ""
  string

  Search text it opens with while uncontrolled; the input is back to it every time it reopens.

• onQueryChange
  (query: string) => void

  Fires on every keystroke in the input (and when a page push or pop clears it).

• shortcutdefault "mod+k"
  string

  Toggles the menu from anywhere (⌘K on Apple devices, Ctrl+K elsewhere). "" binds nothing. The showcase binds ⌘K itself, so the demo uses ⌘J while this is mod+k.

• placeholderdefault "Type a command or search…"
  string

  The input placeholder on the root page; a page can set its own.

• emptyTextdefault "No results"
  string

  Shown when nothing matches.

• loadingTextdefault "Searching…"
  string

  Shown while loadItems runs and nothing else is listed yet; also the spinner's accessible name.

• recentdefault true
  boolean

  A Recent group of the last picked items (by id) while the query is empty on the root page. Page pushers are not recorded.

• recentKeydefault "command-menu:recent"
  string

  Local storage key for the recents (use-persisted-state). "" keeps them in memory for the session.

• maxRecentdefault 5
  number

  How many recent items to show.

• footerdefault true
  boolean

  The key hints bar (↑↓ navigate, ↵ open, esc close) and the result count. Fine pointers only; never on the phone sheet.

• sizedefault "md"
  "sm" | "md" | "lg"

  Width 480 / 640 / 800px (the sheet from 768px with mode sheet: 420 / 560 / 720px).

• radiusdefault "lg"
  "none" | "sm" | "md" | "lg" | "full"

  Corner radius of the panel (0 / 12 / 16 / 24px) and, scaled down, of its rows and the phone search field. full keeps the 24px panel with pill rows.

• highlightMatchesdefault true
  boolean

  Matched letters in bold. Matching ignores case and diacritics, so “cafe” highlights “Café”.

• globalShortcutsdefault false
  boolean

  Also binds every item's shortcut on the page while mounted, even closed (a bare key only outside text fields). Off: item shortcuts work only while the menu is open.

• loopdefault true
  boolean

  Arrow keys wrap from the last item to the first.

• responsivedefault true
  boolean

  A full-height bottom sheet below 768px, with the keyboard raised at once.

• modedefault "auto"
  "auto" | "dialog" | "sheet"

  auto: the dialog from 768px and the sheet below (with responsive). dialog or sheet: that at every width.

• inlinedefault false
  boolean

  Renders the palette in place instead of a dialog (a help page, a sidebar search). open and the shortcut are ignored; Escape clears.

• filter
  (item: CommandItem, query: string) => (number | null)

  Custom ranking: higher first, null hides. Default: text-match over the label, keywords, description and the shortcut, best first inside each group.

• onSelect
  (item: CommandItem) => void

  After every pick (not page pushes), once the item's own onSelect settled.

• linkComponent
  (props: LinkComponentProps) => ReactNode

  Router link for href items; defaults to the LinkProvider's. Clicks go through the link (cmd-click opens a new tab), Enter through useNavigate.

• container
  HTMLElement | null

  Portal target, default document.body.

• labels
  { title?; navigate?; select?; close?; back?; clear?; cancel?; recent?; error?; retry?; results?: (n) => string }

  Every other visible or spoken string: the hidden dialog title ("Command menu"), the footer hints (clear is the esc hint of an inline palette), the sheet's Cancel, the Recent heading, the error row and the announced result count.

• classNames
  Partial<Record<"overlay" | "content" | "header" | "breadcrumb" | "input" | "spinner" | "esc" | "list" | "group" | "groupHeading" | "item" | "icon" | "label" | "description" | "badge" | "shortcut" | "empty" | "loading" | "error" | "footer", string>>

  Extra classes for the inner parts.

Parts

FAQ

Used in

More React navigation components