Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/dip/cmdk/llms.txt

Use this file to discover all available pages before exploring further.

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

​
label
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.
​
shouldFilter
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.
​
filter
(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.
​
defaultValue
string
The value of the item that is selected when the menu first renders. Has no effect if value is provided (controlled mode).
​
value
string
The controlled value of the currently selected item. Use together with onValueChange to manage selection state externally.
​
onValueChange
(value: string) => void
Callback fired when the selected item changes. Receives the value string of the newly selected item.
​
loop
boolean
default:"false"
When true, keyboard navigation wraps around: pressing ArrowDown on the last item moves focus to the first item, and vice versa.
​
disablePointerSelection
boolean
default:"false"
When true, moving the pointer over an item does not select it. Selection only changes through keyboard navigation or clicks.
​
vimBindings
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.

​
Keyboard navigation

KeyAction
ArrowDownSelect next item
ArrowUpSelect previous item
Alt+ArrowDownSelect first item in the next group
Alt+ArrowUpSelect first item in the previous group
Meta+ArrowDownSelect last item
Meta+ArrowUpSelect first item
HomeSelect first item
EndSelect last item
EnterTrigger onSelect on the selected item
Ctrl+N / Ctrl+JSelect next item (vim bindings, when enabled)
Ctrl+P / Ctrl+KSelect 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>
)

​
Looping navigation

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>