Command

Usage

import { Command, Portal, useCommandCollection } from "@chakra-ui/react"

<Command.Provider>
  <Command.Dialog>
    <Command.DialogTrigger />
    <Portal>
      <Command.DialogBackdrop />
      <Command.DialogContent>
        <Command.Root>
          <Command.Label />
          <Command.Control>
            <Command.Indicator />
            <Command.Input />
            <Command.ClearTrigger />
          </Command.Control>
          <Command.List>
            <Command.Loading />
            <Command.ItemGroup>
              <Command.ItemGroupLabel />
              <Command.Item>
                <Command.ItemText />
                <Command.ItemCommand />
              </Command.Item>
            </Command.ItemGroup>
            <Command.Separator />
            <Command.Empty />
          </Command.List>
          <Command.Footer />
        </Command.Root>
      </Command.DialogContent>
    </Portal>
  </Command.Dialog>
</Command.Provider>

Items are data. useCommandCollection ranks them as you type, and Command.Provider shares the result with the dialog and the root.

const command = useCommandCollection({ initialItems: commands })

<Command.Provider value={command}>
  <Command.Dialog>
    <Portal>
      <Command.DialogBackdrop />
      <Command.DialogContent>
        <Command.Root>{/* ... */}</Command.Root>
      </Command.DialogContent>
    </Portal>
  </Command.Dialog>
</Command.Provider>

• Selecting an item runs its onSelect and closes the dialog. Set closeOnSelect: false on the item, or on Root, to keep it open.
• Holding ⌘, Ctrl, Shift, or Alt while selecting keeps the dialog open, e.g. to open several links in new tabs. onSelect receives them as modifiers.
• The dialog clears the query after it closes.
• Command.DialogBackdrop is optional.
• Set disabled: true on an item to show it without letting it run.
• There's no built-in shortcut to open the dialog. Bind ⌘K with the tool your app already uses, as in Hotkeys.

Command runs actions and keeps no selected value. For a picker, use Combobox or Listbox.

Coming from cmdk

In cmdk, items are elements that cmdk filters in the DOM. Here, items are data that useCommandCollection ranks.

Examples

Inline

Render Command.Root without a dialog and pass the collection with the command prop. Add a Command.Label to name the search, visually hidden if needed. In a dialog, the hidden title from Command.DialogContent names it instead.

Groups

Pass groupBy to useCommandCollection. Items are ranked within each group, and the group order stays fixed while you type.

Keywords

Add keywords to an item so other words find it, like "preferences" for Settings. Keyword matches rank just below label matches.

Highlight Matches

Set highlight on ItemText to bold the matched characters, including fuzzy and camelCase matches.

<Command.ItemText highlight>{item.label}</Command.ItemText>

Controlled Search

Pass query and onQueryChange to keep the query in your own state, for example to sync it with the URL.

Prefix Search

Type >, @, or # first to search only commands, people, or channels. Backspace on an empty input clears the scope.

Tabs

Filter the items by the active tab.

Async Content

Pass load to fetch items as you type. Stale requests are cancelled, and Loading and Empty never show at the same time.

Load More

Return { items, cursor } from load to page through results. Call command.loadMore() when the user reaches the end of the list and command.hasMore is true.

Bring Your Own Data

To fetch with your own data layer, such as TanStack Query, control the query and pass the results in. Set filter: null so server results show as returned.

const [query, setQuery] = useState("")
const people = useQuery({
  queryKey: ["people", query],
  queryFn: () => searchPeople(query),
})

const command = useCommandCollection({
  initialItems: people.data ?? [],
  query,
  onQueryChange: setQuery,
  filter: null,
})

<Command.Root command={command} loading={people.isFetching}>
  {/* ... */}
</Command.Root>

Nested

Give an item a parent to put it on that item's page. Nothing else changes in the markup.

const command = useCommandCollection({
  initialItems: [
    { label: "Change status...", value: "status" },
    { label: "Done", value: "status:done", parent: "status" },
  ],
  deepSearch: true,
})

• Selecting an item with children opens its page.
• Escape goes back to the previous page, then closes the dialog.
• Backspace on an empty input goes up a page.
• Going back restores the query and highlights the item you came from.
• command.pages is the trail of open pages, for a breadcrumb.
• With deepSearch, a query also matches items in nested pages. command.getPath(item) returns where a match lives.
• To open a page directly, such as from a shortcut, call command.reset("status") before opening the dialog. Escape then closes it.

Async Pages

Set page: true on an item to open a page that loads its own items. load receives the current page and reloads when it changes.

Input Pages

Build a page's items from the query, such as "Rename to …" or "Invite by email".

Hotkeys

Register the same items with useHotkeys so their shortcuts work while the menu is closed. Format them per platform with useFormatHotkey.

Store

Use useCommand with Command.RootProvider to work with the command's state from outside, such as controlling the dialog from a ⌘K shortcut.

Links

Render items as anchors with asChild, so links open with a click, a middle-click, or Enter. ⌘+Enter or Ctrl+Enter opens the link in a new tab, like ⌘+click.

Recent Items

Store recently used commands and show them in their own group.

Toggle Items

Set closeOnSelect={false} and toggle values in onSelect to pick several items without closing.

Footer Actions

Show shortcut hints or actions below the list with Footer.

Empty State

Customize what Empty shows when nothing matches.

Virtualized

Virtualize the list for large datasets. Pass a deferred copy of the query as filterQuery so typing stays responsive. Enter still runs the top match for what you typed.

const [query, setQuery] = useState("")
const command = useCommandCollection({
  initialItems,
  query,
  onQueryChange: setQuery,
  filterQuery: useDeferredValue(query),
})

Sizes

size on Command.Root sets the density. size on Command.Dialog sets the width.

Props

Root

RootProvider

Label

Input

Control

Indicator

List

Loading

Item

ItemText

ItemGroup

ItemGroupLabel

ItemCommand

Empty

Separator

Footer