Shadcn Syntax Command

CommandDialog

Wraps Command inside shadcn's Dialog. Source-verified at apps/v4/registry/new-york-v4/ui/command.tsx :

• Injects a <DialogHeader className="sr-only"><DialogTitle>{title}</DialogTitle><DialogDescription>{description}</DialogDescription></DialogHeader> so the dialog has an accessible name.
• Default title is "Command Palette", default description is "Search for a command to run...".
• Forwards every Dialog prop (open, onOpenChange, defaultOpen, modal, container) via spread.
• Applies a long [&_[cmdk-*]] Tailwind selector chain to style the embedded cmdk parts.

Use it for global launchers and modal palettes. NEVER add a visible DialogTitle child inside CommandDialog (the sr-only one already wires aria-labelledby).

CommandInput

Search input. Controlled via value + onValueChange. cmdk normalises the value (trim + lowercase) before comparing to item values. shadcn wraps the input in a <div data-slot="command-input-wrapper"> with a SearchIcon prefix.

const [query, setQuery] = useState("")
<CommandInput value={query} placeholder="Search..." />

ALWAYS use value + onValueChange when you need server-side filtering or analytics. For pure client-side filtering you can omit both and let cmdk track the query internally.

CommandList

Scrollable container. Default styling : max-h-[300px] scroll-py-1 overflow-x-hidden overflow-y-auto. The --cmdk-list-height CSS variable is set by cmdk to the natural height of the visible items, enabling smooth height animation if you opt in.

CommandEmpty

Renders automatically when the filtered result count is zero. REQUIRED for accessible empty-state communication. Without it, the list area silently collapses to zero height.

To customise the message with the live query :

import { useCommandState } from "cmdk"

function EmptyWithQuery() {
  const search = useCommandState((state) => state.search)
  return <CommandEmpty>No results for "{search}".</CommandEmpty>
}

CommandGroup

Groups items under a heading string. cmdk applies a hidden HTML attribute to the group when every child has been filtered out (the group does NOT unmount). Use the forceMount prop to keep the group visible regardless of filter.

CommandItem

Selectable row. Key props :

• value?: string : filter key. If omitted, cmdk infers from textContent. ALWAYS provide explicitly for items whose visible text might collide or contain icons.
• keywords?: string[] : extra terms that match this item during filtering (treated as aliases ; trimmed).
• onSelect?: (value: string) => void : fires when the user picks this item (Enter or click). value is the trimmed value prop or inferred text.
• disabled?: boolean : when true, the item is skipped by keyboard nav and visually muted via data-disabled="true".
• forceMount?: boolean : keep this item rendered even when the filter would hide it. Useful for "always-show" entries (e.g., "Create new...").

Data attributes : data-selected="true" when highlighted, data-disabled="true" when disabled.

CommandSeparator

Visual <div role="separator">. Hidden via cmdk's hidden attribute while the search query is non-empty (because the filter has reordered items and separators break the visual hierarchy). Pass alwaysRender to force visibility.

CommandShortcut

Pure <span> with ml-auto text-xs tracking-widest text-muted-foreground. Not a cmdk part ; shadcn-only addition. Place inside a CommandItem to render a keyboard-shortcut hint :

<CommandItem value="profile">
  Profile
  <CommandShortcut>Ctrl+P</CommandShortcut>
</CommandItem>

a11y : keyboard navigation comes from cmdk

cmdk implements the WAI-ARIA Combobox / Listbox keyboard model :

Inside CommandDialog the dialog adds Esc (close) and Tab (focus trap). cmdk handles the listbox roles ; you only need to provide unique item values and visible text.

Cmd+K global hotkey : the canonical pattern

"use client"

import { useEffect, useState } from "react"
import { CommandDialog, CommandInput, CommandList, CommandEmpty,
         CommandGroup, CommandItem } from "@/components/ui/command"

export function CommandMenu() {
  const [open, setOpen] = useState(false)

  useEffect(() => {
    function onKeyDown(e: KeyboardEvent) {
      if (e.key === "k" && (e.metaKey || e.ctrlKey)) {
        e.preventDefault()
        setOpen((current) => !current)
      }
    }
    document.addEventListener("keydown", onKeyDown)
    return () => document.removeEventListener("keydown", onKeyDown)
  }, [])

  return (
    <CommandDialog open={open}
      <CommandInput placeholder="Type a command or search..." />
      <CommandList>
        <CommandEmpty>No results found.</CommandEmpty>
        <CommandGroup heading="Suggestions">
          <CommandItem value="calendar" => setOpen(false)}>
            Calendar
          </CommandItem>
        </CommandGroup>
      </CommandList>
    </CommandDialog>
  )
}

Three details that MUST be present :

1. e.metaKey || e.ctrlKey : covers macOS (Cmd) AND Windows / Linux (Ctrl) in one branch.
2. e.preventDefault() BEFORE the state toggle : Chrome maps Cmd+K to the URL-bar suggestions ; without preventDefault the browser intercepts the key.
3. return () => document.removeEventListener("keydown", onKeyDown) : the cleanup. Without it the listener stacks on every remount, the toggles compound, and React DevTools flags a leak.

NEVER place the listener on window and the cleanup on document (or vice versa) ; the removal MUST target the same target the registration used.

Async filtering pattern : shouldFilter={false} + manual fetch

const [query, setQuery] = useState("")
const [items, setItems] = useState<Item[]>([])
const [loading, setLoading] = useState(false)

useEffect(() => {
  if (!query) { setItems([]); return }
  const controller = new AbortController()
  setLoading(true)
  fetch(`/api/search?q=${encodeURIComponent(query)}`, { signal: controller.signal })
    .then((r) => r.json())
    .then((data) => { setItems(data); setLoading(false) })
    .catch(() => { /* aborted */ })
  return () => controller.abort()
}, [query])

return (
  <Command shouldFilter={false}>
    <CommandInput value={query} />
    <CommandList>
      {loading && <CommandLoading>Searching…</CommandLoading>}
      <CommandEmpty>No results.</CommandEmpty>
      {items.map((it) => (
        <CommandItem key={it.id} value={it.id} => pick(it)}>
          {it.label}
        </CommandItem>
      ))}
    </CommandList>
  </Command>
)

Note : CommandLoading is imported directly from cmdk, NOT re-exported by shadcn's command.tsx. Import it as import { CommandLoading } from "cmdk" or wrap your own re-export.

ALWAYS pair shouldFilter={false} with a manual fetch + filter ; otherwise the input becomes decorative and the list shows every item.

Companion Skills

• shadcn-syntax-selectors (B5 sibling) : the Select vs Native Select vs Combobox vs Command-as-palette DECISION TREE. Read FIRST when choosing between primitives ; this skill assumes Command was already the right answer.
• shadcn-syntax-dialog (B4) : the Dialog primitive that CommandDialog wraps internally. Read for the controlled-state contract (open + onOpenChange), sr-only DialogTitle pattern, Portal stacking, the showCloseButton prop that CommandDialog forwards.
• shadcn-errors-cmdk-version-drift (B13 forward-pointer) : the three top-15 GitHub issues (#2944 / #2980 / #3051) that all trace to cmdk API drift between releases. Read when you hit "TypeError : undefined is not iterable" or "items unclickable" on an existing project that worked yesterday.
• shadcn-syntax-drawer (B5 sibling) : the vaul-backed Drawer ; the Drawer-plus-Command pairing has a known focus quirk forwarded into the anti-patterns of this skill (entry #7 in references/anti-patterns.md).
• shadcn-impl-component-install : the post-install fix-ups for cmdk version pinning ; relevant whenever shadcn add command overwrites a working file.

Reference Links

• references/methods.md : full prop signatures for all nine primitives, the three-arg filter signature, shouldFilter semantics, value + onValueChange contracts, useCommandState hook, data-attributes.
• references/examples.md : five working recipes (Cmd+K dialog, async server filter with CommandLoading, palette with groups + shortcuts, nested sub-pages, Command inside Popover for Combobox).
• references/anti-patterns.md : seven anti-patterns with WHY and FIX (stale filter arity, lowercase normalisation gotcha, missing CommandEmpty, leaked keydown listener, shouldFilter without manual filtering, duplicate item values, Drawer + Command focus loss).

Sources

All claims in this skill trace to URLs in SOURCES.md :

• https://ui.shadcn.com/docs/components/radix/command (canonical Command docs, composition example, CommandDialog default props)
• https://cmdk.paco.me (underlying cmdk library docs, three-arg filter signature, shouldFilter / loop / forceMount props, useCommandState hook, async example)
• https://github.com/shadcn-ui/ui (apps/v4/registry/new-york-v4/ui/command.tsx, verbatim v4 source ; CommandDialog sr-only header pattern)
• https://github.com/shadcn-ui/ui/issues/2944 (Command/Combobox TypeError + unclickable items, 117 reactions, cmdk breaking change)
• https://github.com/shadcn-ui/ui/issues/2980 (Combobox "undefined is not iterable", 87 reactions)
• https://github.com/shadcn-ui/ui/issues/3051 (Combobox Array.from requires array-like, 42 reactions)

Verified 2026-05-19.