Nested items

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.

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>
  )
}

When the search input is empty, 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.

⌘I

Get Started

Components

Guides

Examples

Nested items

The pages pattern

Show sub-items when searching

​The pages pattern

​Breadcrumb badges

​Show sub-items when searching

The pages pattern

Breadcrumb badges

Show sub-items when searching