Documentation Index
Fetch the complete documentation index at: https://mintlify.com/dip/cmdk/llms.txt
Use this file to discover all available pages before exploring further.
Selecting a command item often should reveal a deeper set of related items — for example, selecting “Change theme…” should show “Dark” and “Light” options. cmdk implements this with a pages pattern: a plain array of strings that acts as a navigation stack.
The pages pattern
Track which page you’re on with useState. Render different items depending on the active page. Push to the stack when an item is selected; pop from the stack when Escape or Backspace is pressed:
import { Command } from 'cmdk'
function CommandMenu() {
const [search, setSearch] = React.useState('')
const [pages, setPages] = React.useState<string[]>([])
const page = pages[pages.length - 1]
return (
<Command
onKeyDown={(e) => {
// Escape goes to previous page
// Backspace goes to previous page when search is empty
if (e.key === 'Escape' || (e.key === 'Backspace' && !search)) {
e.preventDefault()
setPages((pages) => pages.slice(0, -1))
}
}}
>
<Command.Input value={search} onValueChange={setSearch} />
<Command.List>
{!page && (
<>
<Command.Item onSelect={() => setPages([...pages, 'projects'])}>
Search projects…
</Command.Item>
<Command.Item onSelect={() => setPages([...pages, 'teams'])}>
Join a team…
</Command.Item>
</>
)}
{page === 'projects' && (
<>
<Command.Item>Project A</Command.Item>
<Command.Item>Project B</Command.Item>
</>
)}
{page === 'teams' && (
<>
<Command.Item>Team 1</Command.Item>
<Command.Item>Team 2</Command.Item>
</>
)}
</Command.List>
</Command>
)
}
Reset the search value when navigating to a new page so the new set of items is not pre-filtered by whatever the user typed previously.
Breadcrumb badges
The Vercel example shows the active page stack as badges rendered above the input — a useful affordance so users know where they are:
<Command>
<div>
{pages.map((p) => (
<span key={p} className="badge">
{p}
</span>
))}
</div>
<Command.Input
value={search}
onValueChange={setSearch}
placeholder={page ? `Search ${page}…` : 'What do you need?'}
/>
{/* list */}
</Command>
Show sub-items when searching
Sometimes you want sub-items to only appear when the user is actively searching — they are hidden at rest but surface during a query. Use useCommandState to read the current search string and conditionally render:
import { Command, useCommandState } from 'cmdk'
function SubItem(props: React.ComponentProps<typeof Command.Item>) {
const search = useCommandState((state) => state.search)
if (!search) return null
return <Command.Item {...props} />
}
function CommandMenu() {
return (
<Command>
<Command.Input />
<Command.List>
<Command.Item>Change theme…</Command.Item>
<SubItem>Change theme to dark</SubItem>
<SubItem>Change theme to light</SubItem>
</Command.List>
</Command>
)
}
SubItem returns null and the sub-items are not in the DOM. As soon as the user types, they appear and are scored alongside all other items.
The SubItem pattern is great for surfacing deeply nested actions (e.g., “Open project settings > Billing”) without cluttering the default view.
