> ## 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.

# Nested items

> Navigate to sub-pages of items using a simple pages stack. Escape or Backspace returns to the previous page.

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:

```tsx theme={null}
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>
  )
}
```

<Note>
  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.
</Note>

## 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:

```tsx theme={null}
<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:

```tsx theme={null}
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.

<Tip>
  The `SubItem` pattern is great for surfacing deeply nested actions (e.g., "Open project settings > Billing") without cluttering the default view.
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.