Command Stack

Installation

pnpm dlx shadcn@latest add @diceui/command-stack

Layout

Import the parts and compose them together.

import {
  CommandStack,
  CommandStackBreadcrumb,
  CommandStackEmpty,
  CommandStackGroup,
  CommandStackInput,
  CommandStackItem,
  CommandStackList,
  CommandStackPage,
  CommandStackShortcut,
} from "@/components/ui/command-stack";
 
return (
  <CommandStack>
    <CommandStackBreadcrumb />
    <CommandStackInput />
    <CommandStackList>
      <CommandStackEmpty />
      <CommandStackPage value="root">
        <CommandStackGroup>
          <CommandStackItem page="projects">
            <CommandStackShortcut />
          </CommandStackItem>
        </CommandStackGroup>
      </CommandStackPage>
      <CommandStackPage value="projects">
        <CommandStackItem />
      </CommandStackPage>
    </CommandStackList>
  </CommandStack>
)

Examples

Popover

Put the stack in a popover for nested menus, such as a filter menu where each filter opens its options. Set selectionMode on a page to make its items toggleable, and control the selection with value and onValueChange. The stack goes back to the root page whenever the popover closes.

Command Palette

Render the stack inside CommandDialog to build a command palette. This example opens with ⌘ J, since ⌘ K opens the docs search.

Workspace

A workspace menu that nests pages several levels deep, from members to a member's role. Items can show avatars, descriptions and trailing details.

Async

Load a page's items when it opens. useCommandStack gives access to the active page, and CommandStackLoading hides the empty state while items load.

API Reference

CommandStack

The root component. It keeps the stack of open pages and the search value, and clears the search whenever the page changes.

CommandStackBreadcrumb

Shows the open pages, using each page's label.

CommandStackInput

The search input. Pressing Backspace while it's empty goes back a page.

CommandStackList

The scrollable list of pages, groups and items.

CommandStackEmpty

Shown when no items match the search. It stays hidden while a CommandStackLoading is rendered.

CommandStackLoading

Shown while a page's items load.

CommandStackPage

A page of items. Only the active page renders its children.

CommandStackGroup

A group of items with an optional heading.

CommandStackItem

A selectable item. Set page to open a page when it's selected, or give it a value on a page with a selectionMode to make it toggleable.

CommandStackShortcut

A keyboard shortcut hint shown at the end of an item.

CommandStackSeparator

A line between groups.

useCommandStack

Reads and changes the stack's pages from any component inside it. It returns pages, activePage, search, value, pushPage(page), popPage(), setPages(pages) and setValue(value).

import { useCommandStack } from "@/components/ui/command-stack";
 
function OpenSettings() {
  const { pushPage } = useCommandStack();
 
  return (
    <CommandStackItem onSelect={() => pushPage("settings")}>
      Settings
    </CommandStackItem>
  );
}

Accessibility

The input keeps focus while you move between pages. The breadcrumb is a labelled navigation landmark that marks the current page, and opening a page announces its label to screen readers.

Keyboard Interactions