# Command

URL: https://ark-ui.com/docs/react/components/command
Markdown: https://ark-ui.com/docs/react/components/command.md

A searchable list of actions for command palettes and quick switchers.

---

---
id: command
title: Command
description: A searchable list of actions for command palettes and quick switchers.
status: new
---



## Anatomy

```tsx
<Command.Root>
  <Command.Label />
  <Command.Control>
    <Command.Input />
  </Command.Control>
  <Command.List>
    <Command.ItemGroup>
      <Command.ItemGroupLabel />
      <Command.Item>
        <Command.ItemText />
      </Command.Item>
    </Command.ItemGroup>
  </Command.List>
  <Command.Empty />
</Command.Root>
```

## Examples

### Basic

Pass a `collection` to `Command.Root` and render the filtered items from `Command.Context`. Typing filters the items,
the arrow keys, Home, and End move the highlight while focus stays in the input, and Enter or a click calls `onSelect`.

```tsx
import { Command, createListCollection } from '@ark-ui/react/command'
import { CopyIcon, FilePlusIcon, FolderOpenIcon, SaveIcon, SearchIcon, SettingsIcon } from 'lucide-react'
import { useState } from 'react'
import styles from 'styles/command.module.css'

const collection = createListCollection({
  items: [
    { value: 'new-file', label: 'New file', icon: FilePlusIcon, shortcut: '⌘N' },
    { value: 'open-file', label: 'Open file', icon: FolderOpenIcon, shortcut: '⌘O' },
    { value: 'save', label: 'Save', icon: SaveIcon, shortcut: '⌘S' },
    { value: 'copy-path', label: 'Copy path', icon: CopyIcon, shortcut: '⌥⌘C' },
    { value: 'settings', label: 'Open settings', icon: SettingsIcon, shortcut: '⌘,' },
  ],
})

export const Basic = () => {
  const [selected, setSelected] = useState<string | null>(null)

  return (
    <div className="stack">
      <output>Selected: {selected ?? 'none'}</output>
      <Command.Root
        className={styles.Root}
        collection={collection}
        onSelect={(details) => setSelected(details.itemValue)}
      >
        <Command.Label className={styles.Label}>Commands</Command.Label>
        <Command.Control className={styles.Control}>
          <SearchIcon />
          <Command.Input className={styles.Input} placeholder="Type a command or search..." />
        </Command.Control>
        <Command.Context>
          {(command) => (
            <Command.List className={styles.List}>
              {command.collection.items.map((item) => (
                <Command.Item key={item.value} item={item} className={styles.Item}>
                  <span className={styles.ItemStart}>
                    <item.icon />
                    <Command.ItemText className={styles.ItemText}>{item.label}</Command.ItemText>
                  </span>
                  <kbd className={styles.Shortcut}>{item.shortcut}</kbd>
                </Command.Item>
              ))}
            </Command.List>
          )}
        </Command.Context>
        <Command.Empty className={styles.Empty}>No commands found</Command.Empty>
      </Command.Root>
    </div>
  )
}
```

### Dialog

Put the command inside a `Dialog` to build a command palette. Open it with a keyboard shortcut using `useHotkey`, and
give the dialog content an `aria-label`.

```tsx
import { Command, createListCollection } from '@ark-ui/react/command'
import { Dialog } from '@ark-ui/react/dialog'
import { useHotkey } from '@ark-ui/react/hotkeys'
import { Portal } from '@ark-ui/react/portal'
import {
  CornerDownLeftIcon,
  FilePlusIcon,
  FolderOpenIcon,
  SaveIcon,
  SearchIcon,
  SettingsIcon,
  TerminalIcon,
} from 'lucide-react'
import { useState } from 'react'
import button from 'styles/button.module.css'
import styles from 'styles/command.module.css'

const collection = createListCollection({
  items: [
    { value: 'new-file', label: 'New file', icon: FilePlusIcon, shortcut: '⌘N' },
    { value: 'open-file', label: 'Open file', icon: FolderOpenIcon, shortcut: '⌘O' },
    { value: 'save', label: 'Save', icon: SaveIcon, shortcut: '⌘S' },
    { value: 'terminal', label: 'Toggle terminal', icon: TerminalIcon, shortcut: '⌃`' },
    { value: 'settings', label: 'Open settings', icon: SettingsIcon, shortcut: '⌘,' },
  ],
})

export const WithDialog = () => {
  const [open, setOpen] = useState(false)
  const [lastRun, setLastRun] = useState<string | null>(null)

  useHotkey({ hotkey: 'mod+K', action: () => setOpen((value) => !value) })

  return (
    <div className="stack">
      <output>Ran: {lastRun ?? 'nothing yet'}</output>
      <Dialog.Root lazyMount unmountOnExit open={open} onOpenChange={(details) => setOpen(details.open)}>
        <Dialog.Trigger className={button.Root}>
          Search commands <kbd>⌘K</kbd>
        </Dialog.Trigger>
        <Portal>
          <Dialog.Backdrop className={styles.Backdrop} />
          <Dialog.Positioner className={styles.Positioner}>
            <Dialog.Content className={styles.Content} aria-label="Command palette">
              <Command.Root
                className={styles.Root}
                collection={collection}
                onSelect={(details) => {
                  setLastRun(details.itemValue)
                  setOpen(false)
                }}
              >
                <Command.Label className={styles.Label}>Commands</Command.Label>
                <Command.Control className={styles.Control}>
                  <SearchIcon />
                  <Command.Input className={styles.Input} placeholder="Type a command or search..." />
                </Command.Control>
                <Command.Context>
                  {(command) => (
                    <Command.List className={styles.List}>
                      {command.collection.items.map((item) => (
                        <Command.Item key={item.value} item={item} className={styles.Item}>
                          <span className={styles.ItemStart}>
                            <item.icon />
                            <Command.ItemText className={styles.ItemText}>{item.label}</Command.ItemText>
                          </span>
                          <kbd className={styles.Shortcut}>{item.shortcut}</kbd>
                        </Command.Item>
                      ))}
                    </Command.List>
                  )}
                </Command.Context>
                <Command.Empty className={styles.Empty}>No commands found</Command.Empty>
              </Command.Root>
              <div className={styles.Footer}>
                <span className={styles.FooterHint}>
                  <kbd className={styles.Shortcut}>↑↓</kbd> Navigate
                </span>
                <span className={styles.FooterHint}>
                  <kbd className={styles.Shortcut}>
                    <CornerDownLeftIcon />
                  </kbd>
                  Run
                </span>
                <span className={styles.FooterHint}>
                  <kbd className={styles.Shortcut}>esc</kbd> Close
                </span>
              </div>
            </Dialog.Content>
          </Dialog.Positioner>
        </Portal>
      </Dialog.Root>
    </div>
  )
}
```

### Groups

Use `groupBy` on the collection and render `collection.group()` with `ItemGroup` and `ItemGroupLabel`. Groups with no
matching items are not rendered. Disabled items are skipped by the keyboard.

```tsx
import { Command, createListCollection } from '@ark-ui/react/command'
import { SearchIcon } from 'lucide-react'
import styles from 'styles/command.module.css'

const collection = createListCollection({
  items: [
    { value: 'calendar', label: 'Calendar', group: 'Suggestions' },
    { value: 'emoji', label: 'Search emoji', group: 'Suggestions' },
    { value: 'calculator', label: 'Calculator', group: 'Suggestions', disabled: true },
    { value: 'profile', label: 'Profile', group: 'Settings' },
    { value: 'billing', label: 'Billing', group: 'Settings' },
    { value: 'preferences', label: 'Preferences', group: 'Settings' },
  ],
  groupBy: (item) => item.group,
})

export const Groups = () => (
  <Command.Root className={styles.Root} collection={collection}>
    <Command.Label className={styles.Label}>Commands</Command.Label>
    <Command.Control className={styles.Control}>
      <SearchIcon />
      <Command.Input className={styles.Input} placeholder="Search..." />
    </Command.Control>
    <Command.Context>
      {(command) => (
        <Command.List className={styles.List}>
          {command.collection.group().map(([group, items]) => (
            <Command.ItemGroup key={group} className={styles.ItemGroup}>
              <Command.ItemGroupLabel className={styles.ItemGroupLabel}>{group}</Command.ItemGroupLabel>
              {items.map((item) => (
                <Command.Item key={item.value} item={item} className={styles.Item}>
                  <Command.ItemText className={styles.ItemText}>{item.label}</Command.ItemText>
                </Command.Item>
              ))}
            </Command.ItemGroup>
          ))}
        </Command.List>
      )}
    </Command.Context>
    <Command.Empty className={styles.Empty}>No results found</Command.Empty>
  </Command.Root>
)
```

### Empty State

`Command.Empty` renders its children when no item matches the input.

```tsx
import { Command, createListCollection } from '@ark-ui/react/command'
import { SearchIcon } from 'lucide-react'
import { useState } from 'react'
import styles from 'styles/command.module.css'

const collection = createListCollection({
  items: [
    { value: 'apple', label: 'Apple' },
    { value: 'banana', label: 'Banana' },
    { value: 'cherry', label: 'Cherry' },
  ],
})

export const EmptyState = () => {
  const [inputValue, setInputValue] = useState('xyz')

  return (
    <Command.Root
      className={styles.Root}
      collection={collection}
      inputValue={inputValue}
      onInputValueChange={(details) => setInputValue(details.inputValue)}
    >
      <Command.Label className={styles.Label}>Fruits</Command.Label>
      <Command.Control className={styles.Control}>
        <SearchIcon />
        <Command.Input className={styles.Input} placeholder="Search fruits..." />
      </Command.Control>
      <Command.Context>
        {(command) => (
          <Command.List className={styles.List}>
            {command.collection.items.map((item) => (
              <Command.Item key={item.value} item={item} className={styles.Item}>
                <Command.ItemText className={styles.ItemText}>{item.label}</Command.ItemText>
              </Command.Item>
            ))}
          </Command.List>
        )}
      </Command.Context>
      <Command.Empty className={styles.Empty}>No results for “{inputValue}”</Command.Empty>
    </Command.Root>
  )
}
```

### Keywords

Items are fuzzy-matched on their text and an optional `keywords` array, best match first.

```tsx
{ value: 'settings', label: 'Open settings', keywords: ['preferences', 'config'] }
```

```tsx
import { Command, createListCollection } from '@ark-ui/react/command'
import { SearchIcon } from 'lucide-react'
import styles from 'styles/command.module.css'

const collection = createListCollection({
  items: [
    { value: 'theme', label: 'Toggle theme', keywords: ['dark', 'light', 'appearance'] },
    { value: 'sign-out', label: 'Sign out', keywords: ['logout', 'exit'] },
    { value: 'shortcuts', label: 'Keyboard shortcuts', keywords: ['hotkeys', 'keybindings'] },
  ],
})

export const Keywords = () => (
  <Command.Root className={styles.Root} collection={collection}>
    <Command.Label className={styles.Label}>Commands</Command.Label>
    <Command.Control className={styles.Control}>
      <SearchIcon />
      <Command.Input className={styles.Input} placeholder="Try “dark” or “logout”..." />
    </Command.Control>
    <Command.Context>
      {(command) => (
        <Command.List className={styles.List}>
          {command.collection.items.map((item) => (
            <Command.Item key={item.value} item={item} className={styles.Item}>
              <Command.ItemText className={styles.ItemText}>{item.label}</Command.ItemText>
            </Command.Item>
          ))}
        </Command.List>
      )}
    </Command.Context>
    <Command.Empty className={styles.Empty}>No commands found</Command.Empty>
  </Command.Root>
)
```

### Pages

Use `createPageListCollection` and give an item a `parent` to put it on that item's page. Selecting the parent opens the
page, Backspace in an empty input goes up, and typing also searches nested pages. Pass `page` to start on one.

```tsx
const collection = createPageListCollection({
  items: [
    { value: 'theme', label: 'Change theme' },
    { value: 'dark', label: 'Dark', parent: 'theme' },
    { value: 'light', label: 'Light', parent: 'theme' },
  ],
  page: 'theme',
})
```

Render breadcrumbs with `path` and a result's location with `getAncestors`. To make Escape go back before the dialog
closes, call `back()` from `onEscapeKeyDown`:

```tsx
const command = useCommand({ collection })

<Dialog.Root
  onEscapeKeyDown={(event) => {
    if (command.canGoBack) {
      event.preventDefault()
      command.back()
    }
  }}
>
  {/* ... */}
  <Command.RootProvider value={command}>{/* ... */}</Command.RootProvider>
</Dialog.Root>
```

```tsx
import { Command, createPageListCollection } from '@ark-ui/react/command'
import { ChevronRightIcon, SearchIcon } from 'lucide-react'
import { useState } from 'react'
import styles from 'styles/command.module.css'

const collection = createPageListCollection({
  items: [
    { value: 'theme', label: 'Change theme' },
    { value: 'language', label: 'Change language' },
    { value: 'sign-out', label: 'Sign out' },
    { value: 'light', label: 'Light', parent: 'theme' },
    { value: 'dark', label: 'Dark', parent: 'theme' },
    { value: 'system', label: 'System', parent: 'theme' },
    { value: 'english', label: 'English', parent: 'language' },
    { value: 'french', label: 'French', parent: 'language' },
  ],
})

export const Pages = () => {
  const [selected, setSelected] = useState<string | null>(null)

  return (
    <div className="stack">
      <output>Selected: {selected ?? 'none'}</output>
      <Command.Root
        className={styles.Root}
        collection={collection}
        onSelect={(details) => setSelected(details.itemValue)}
      >
        <Command.Label className={styles.Label}>Settings</Command.Label>
        <Command.Context>
          {(command) => (
            <>
              <div className={styles.Breadcrumb}>
                <button type="button" onClick={() => command.setPage(null)}>
                  Home
                </button>
                {command.path.map((page) => (
                  <span key={page.value}>
                    <ChevronRightIcon />
                    <button type="button" onClick={() => command.setPage(page.value)}>
                      {page.label}
                    </button>
                  </span>
                ))}
              </div>
              <Command.Control className={styles.Control}>
                <SearchIcon />
                <Command.Input
                  className={styles.Input}
                  placeholder={command.page ? 'Search... (Backspace to go back)' : 'Search settings...'}
                />
              </Command.Control>
              <Command.List className={styles.List}>
                {command.collection.items.map((item) => (
                  <Command.Item key={item.value} item={item} className={styles.Item}>
                    <Command.ItemText className={styles.ItemText}>{item.label}</Command.ItemText>
                    {command.getAncestors(item).length > 0 && (
                      <span className={styles.ItemPath}>
                        {command
                          .getAncestors(item)
                          .map((page) => page.label)
                          .join(' › ')}
                      </span>
                    )}
                    {command.isPage(item) && <ChevronRightIcon />}
                  </Command.Item>
                ))}
              </Command.List>
            </>
          )}
        </Command.Context>
        <Command.Empty className={styles.Empty}>No results found</Command.Empty>
      </Command.Root>
    </div>
  )
}
```

### Async

Load items with `useAsyncList`, call `setFilter` as the input changes, and pass `isLoading` to `loading`. Pass a
`filter` that returns every item, since the server already filtered them.

```tsx
import { useAsyncList } from '@ark-ui/react/collection'
import { Command, createListCollection } from '@ark-ui/react/command'
import { SearchIcon } from 'lucide-react'
import styles from 'styles/command.module.css'

interface Person {
  id: string
  name: string
}

const people: Person[] = [
  { id: 'ada', name: 'Ada Lovelace' },
  { id: 'alan', name: 'Alan Turing' },
  { id: 'grace', name: 'Grace Hopper' },
  { id: 'katherine', name: 'Katherine Johnson' },
  { id: 'linus', name: 'Linus Torvalds' },
  { id: 'margaret', name: 'Margaret Hamilton' },
]

const matchAll = <T,>(items: T[]) => items

export const Async = () => {
  const list = useAsyncList<Person>({
    async load({ filter, signal }) {
      await new Promise((resolve) => setTimeout(resolve, 300))
      if (signal?.aborted) return { items: [] }
      const query = (filter ?? '').toLowerCase()
      return { items: people.filter((person) => person.name.toLowerCase().includes(query)) }
    },
  })

  const collection = createListCollection({
    items: list.items,
    itemToValue: (item) => item.id,
    itemToString: (item) => item.name,
  })

  return (
    <Command.Root
      className={styles.Root}
      collection={collection}
      filter={matchAll}
      loading={list.isLoading}
      onInputValueChange={(details) => list.setFilter(details.inputValue)}
    >
      <Command.Label className={styles.Label}>People</Command.Label>
      <Command.Control className={styles.Control}>
        <SearchIcon />
        <Command.Input className={styles.Input} placeholder="Search people..." />
      </Command.Control>
      <Command.List className={styles.List}>
        {collection.items.map((item) => (
          <Command.Item key={item.id} item={item} className={styles.Item}>
            <Command.ItemText className={styles.ItemText}>{item.name}</Command.ItemText>
          </Command.Item>
        ))}
      </Command.List>
      {list.isLoading && <div className={styles.Loading}>Loading...</div>}
      {!list.isLoading && list.error && <div className={styles.Empty}>{list.error.message}</div>}
      {!list.isLoading && !list.error && <Command.Empty className={styles.Empty}>No people found</Command.Empty>}
    </Command.Root>
  )
}
```

### Root Provider

Use the `useCommand` hook with `RootProvider` to control the command from outside, for example to clear the input.

```tsx
import { Command, createListCollection, useCommand } from '@ark-ui/react/command'
import { SearchIcon } from 'lucide-react'
import button from 'styles/button.module.css'
import styles from 'styles/command.module.css'

const collection = createListCollection({
  items: [
    { value: 'new-file', label: 'New file' },
    { value: 'open-file', label: 'Open file' },
    { value: 'save', label: 'Save' },
  ],
})

export const RootProvider = () => {
  const command = useCommand({ collection })

  return (
    <div className="stack">
      <button type="button" className={button.Root} onClick={() => command.setInputValue('')}>
        Clear search ({command.inputValue || 'empty'})
      </button>
      <Command.RootProvider className={styles.Root} value={command}>
        <Command.Label className={styles.Label}>Commands</Command.Label>
        <Command.Control className={styles.Control}>
          <SearchIcon />
          <Command.Input className={styles.Input} placeholder="Search..." />
        </Command.Control>
        <Command.List className={styles.List}>
          {command.collection.items.map((item) => (
            <Command.Item key={item.value} item={item} className={styles.Item}>
              <Command.ItemText className={styles.ItemText}>{item.label}</Command.ItemText>
            </Command.Item>
          ))}
        </Command.List>
        <Command.Empty className={styles.Empty}>No commands found</Command.Empty>
      </Command.RootProvider>
    </div>
  )
}
```

## Guides

### Custom filtering

Pass `filter` to replace the fuzzy search. It returns the matching items in the order to show them.

```tsx
<Command.Root
  collection={collection}
  filter={(items, query) => items.filter((item) => item.label.toLowerCase().startsWith(query.toLowerCase()))}
/>
```

### Accessibility

The input is a `combobox` that controls the `listbox` and points to the highlighted option with `aria-activedescendant`,
so focus never leaves the input. Result counts are announced to screen readers. Label the command with `Command.Label`,
and label the dialog when you render it in one.

## API Reference

### Props



### Context


