# 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 match on their text and on an optional `keywords` array, so a command can be found by words that aren't in its
label.

```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

Give an item a `parent` value to place it on that item's page. Selecting the parent opens its page instead of calling
`onSelect`, and Backspace in an empty input goes back. Use `pages`, `setPage`, and `isPage` from the context to render
breadcrumbs and page indicators.

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

const collection = createListCollection({
  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.pages.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.isPage(item) && <ChevronRightIcon />}
                  </Command.Item>
                ))}
              </Command.List>
            </>
          )}
        </Command.Context>
        <Command.Empty className={styles.Empty}>No results found</Command.Empty>
      </Command.Root>
    </div>
  )
}
```

### Async

To load items from a server, update the collection as the input value changes, pass a `filter` that keeps every item,
and set `loading` while the request is in flight.

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

const people = [
  'Ada Lovelace',
  'Alan Turing',
  'Grace Hopper',
  'Katherine Johnson',
  'Linus Torvalds',
  'Margaret Hamilton',
]

const search = (query: string) =>
  new Promise<string[]>((resolve) => {
    const q = query.toLowerCase()
    setTimeout(() => resolve(people.filter((name) => name.toLowerCase().includes(q))), 300)
  })

const matchAll = () => true

export const Async = () => {
  const [inputValue, setInputValue] = useState('')
  const [names, setNames] = useState<string[]>([])
  const [loading, setLoading] = useState(true)

  useEffect(() => {
    let active = true
    setLoading(true)
    search(inputValue).then((result) => {
      if (!active) return
      setNames(result)
      setLoading(false)
    })
    return () => {
      active = false
    }
  }, [inputValue])

  const collection = useMemo(
    () =>
      createListCollection({
        items: names.map((name) => ({ value: name.toLowerCase().replace(/\s+/g, '-'), label: name })),
      }),
    [names],
  )

  return (
    <Command.Root
      className={styles.Root}
      collection={collection}
      filter={matchAll}
      loading={loading}
      onInputValueChange={(details) => setInputValue(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.value} item={item} className={styles.Item}>
            <Command.ItemText className={styles.ItemText}>{item.label}</Command.ItemText>
          </Command.Item>
        ))}
      </Command.List>
      {loading && <div className={styles.Loading}>Loading...</div>}
      {!loading && <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

The default filter is a case-insensitive, accent-insensitive match on the item text and its `keywords`. Pass `filter` to
match your own way.

```tsx
<Command.Root collection={collection} filter={(itemText, inputValue) => itemText.startsWith(inputValue)} />
```

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


