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 top0 — 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>
<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)
}}
/>
