Command

Command is the root wrapper for the entire command menu. Render it inline in your UI, or use Command.Dialog to render it in an overlay. It manages all internal state including the current search query, selected item, and filtered results.

import { Command } from 'cmdk'

export function CommandMenu() {
  return (
    <Command label="Command Menu">
      <Command.Input placeholder="Type a command..." />
      <Command.List>
        <Command.Empty>No results found.</Command.Empty>
        <Command.Group heading="Suggestions">
          <Command.Item>Calendar</Command.Item>
          <Command.Item>Search</Command.Item>
          <Command.Item>Settings</Command.Item>
        </Command.Group>
      </Command.List>
    </Command>
  )
}

Data attribute: [cmdk-root]

All item values are trimmed with String.trim() before being used for filtering or comparison.

Props

string

Accessible label for the command menu. Rendered as a visually hidden <label> element associated with the input. Use this to describe the purpose of the menu to screen reader users.

boolean

default:"true"

Set to false to disable automatic filtering and sorting. When disabled, you are responsible for conditionally rendering items based on the current search query. Useful for server-side filtering or virtualized lists.

(value: string, search: string, keywords?: string[]) => number

Custom filter function used to rank each item against the search query. Return a number between 0 and 1, where 1 is the best match and 0 hides the item entirely. Defaults to the built-in command-score algorithm.

string

The value of the item that is selected when the menu first renders. Has no effect if value is provided (controlled mode).

string

The controlled value of the currently selected item. Use together with onValueChange to manage selection state externally.

(value: string) => void

Callback fired when the selected item changes. Receives the value string of the newly selected item.

boolean

default:"false"

When true, keyboard navigation wraps around: pressing ArrowDown on the last item moves focus to the first item, and vice versa.

boolean

default:"false"

When true, moving the pointer over an item does not select it. Selection only changes through keyboard navigation or clicks.

boolean

default:"true"

When true, enables Ctrl+N / Ctrl+J to move down and Ctrl+P / Ctrl+K to move up, mirroring common Vim-style navigation bindings.

Key	Action
`ArrowDown`	Select next item
`ArrowUp`	Select previous item
`Alt+ArrowDown`	Select first item in the next group
`Alt+ArrowUp`	Select first item in the previous group
`Meta+ArrowDown`	Select last item
`Meta+ArrowUp`	Select first item
`Home`	Select first item
`End`	Select last item
`Enter`	Trigger `onSelect` on the selected item
`Ctrl+N` / `Ctrl+J`	Select next item (vim bindings, when enabled)
`Ctrl+P` / `Ctrl+K`	Select previous item (vim bindings, when enabled)

Examples

Controlled selection

Pass value and onValueChange to control which item is selected:

const [value, setValue] = React.useState('apple')

return (
  <Command value={value} onValueChange={setValue}>
    <Command.Input />
    <Command.List>
      <Command.Item value="orange">Orange</Command.Item>
      <Command.Item value="apple">Apple</Command.Item>
    </Command.List>
  </Command>
)

Custom filter function

Replace the default scoring algorithm with your own logic. The function receives the item’s value, the current search query, and returns a score between 0 (hidden) and 1 (best match):

<Command
  filter={(value, search) => {
    if (value.includes(search)) return 1
    return 0
  }}
>
  <Command.Input />
  <Command.List>
    <Command.Item>Apple</Command.Item>
    <Command.Item>Banana</Command.Item>
  </Command.List>
</Command>

Custom filter with keywords

The filter function also receives a third keywords argument — the array passed to each Command.Item. Use it to match against aliases:

<Command
  filter={(value, search, keywords) => {
    const extendedValue = value + ' ' + keywords?.join(' ')
    if (extendedValue.toLowerCase().includes(search.toLowerCase())) return 1
    return 0
  }}
>
  <Command.Input />
  <Command.List>
    <Command.Item keywords={['preferences', 'configuration']}>Settings</Command.Item>
    <Command.Item keywords={['appearance', 'dark mode']}>Theme</Command.Item>
  </Command.List>
</Command>

Disable automatic filtering

Set shouldFilter={false} to take full control of which items are rendered. Useful for server-side search or when you have too many items to filter in the browser:

const [search, setSearch] = React.useState('')
const filteredItems = allItems.filter((item) =>
  item.toLowerCase().includes(search.toLowerCase())
)

return (
  <Command shouldFilter={false}>
    <Command.Input value={search} onValueChange={setSearch} />
    <Command.List>
      {filteredItems.map((item) => (
        <Command.Item key={item} value={item}>
          {item}
        </Command.Item>
      ))}
    </Command.List>
  </Command>
)

Enable wrap-around keyboard navigation so pressing ArrowDown on the last item returns to the first:

<Command loop>
  <Command.Input />
  <Command.List>
    <Command.Item>First</Command.Item>
    <Command.Item>Second</Command.Item>
    <Command.Item>Third</Command.Item>
  </Command.List>
</Command>

⌘I

Get Started

Components

Guides

Examples

Props

Keyboard navigation

Examples

Controlled selection

Custom filter function

Custom filter with keywords

Disable automatic filtering

Looping navigation

​Props

​Keyboard navigation

​Examples

​Controlled selection

​Custom filter function

​Custom filter with keywords

​Disable automatic filtering

​Looping navigation

Props

Keyboard navigation

Examples

Controlled selection

Custom filter function

Custom filter with keywords

Disable automatic filtering

Looping navigation