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.

By default, cmdk uses its built-in command-score algorithm — a fuzzy matching library — to rank items against the current search query. Items with a score above 0 are shown; items are sorted by descending score. Groups are re-ordered by the highest score of any item they contain. Filtering and sorting run synchronously on every keystroke, so the list updates with no visible delay.

​
Default behavior

No configuration needed. Items are filtered and sorted automatically: 
<Command>
  <Command.Input />
  <Command.List>
    <Command.Group heading="Fruits">
      <Command.Item>Apple</Command.Item>
      <Command.Item>Banana</Command.Item>
      <Command.Item>Cherry</Command.Item>
    </Command.Group>
  </Command.List>
</Command>
Item values are always trimmed with .trim() before scoring. If you provide a value prop explicitly, it is trimmed too.

​
Custom filter function

Pass a filter prop to Command to replace the default algorithm. The function receives (value, search, keywords?) and must return a number between 0 and 1:
  • 1 — exact match, shown at the top
  • 0 — no match, hidden
  • Values in between affect sort order
// Exact substring 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>

​
Keywords

Add a keywords prop to Command.Item to provide aliases that also match during search. Keywords are trimmed and passed to your filter function as the third argument: 
<Command.Item keywords={['fruit', 'red']}>Apple</Command.Item>
<Command.Item keywords={['fruit', 'yellow']}>Banana</Command.Item>
To use keywords in a custom filter function: 
<Command
  filter={(value, search, keywords) => {
    const extendValue = value + ' ' + keywords.join(' ')
    if (extendValue.includes(search)) return 1
    return 0
  }}
>
  <Command.Input />
  <Command.List>
    <Command.Item keywords={['fruit', 'red']}>Apple</Command.Item>
    <Command.Item keywords={['veggie', 'green']}>Broccoli</Command.Item>
  </Command.List>
</Command>
Keywords are trimmed with .trim() before being passed to the filter function.

​
Disabling automatic filtering

Set shouldFilter={false} to disable all built-in filtering and sorting. You are then responsible for rendering only the items that should be visible based on the current query: 
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>
)
shouldFilter={false} is recommended when you need to bring your own virtualization or when you are filtering a very large list on the server.

​
Using the default filter directly

cmdk exports defaultFilter, the same function used internally. Import it if you want to extend the default behavior rather than replace it entirely: 
import { Command, defaultFilter } from 'cmdk'

<Command
  filter={(value, search, keywords) => {
    // Pin items that start with the search string to the top
    if (value.startsWith(search)) return 1
    return defaultFilter(value, search, keywords)
  }}
/>