Core API

cmdk-engine is plain TypeScript with zero runtime dependencies. The React provider is built from the pieces on this page. Use them directly to drive another UI, in tests, or on the server. For the provider, hooks and the command object, see the API Reference. The type declarations import React's types for the icon field. Without them in your project, and with skipLibCheck off, icon is typed any instead of failing to compile.

import { createRegistry, createFuzzySearch } from 'cmdk-engine'

const registry = createRegistry()
const unregister = registry.register({ id: 'home', label: 'Home', href: '/' })

const results = createFuzzySearch().search('ho', registry.getAll())
// [{ item: { id: 'home', ... }, score: 0.95 }]

unregister() // remove the command again

createRegistry()

The command store. It is a small publish and subscribe store that works with React's useSyncExternalStore. Subscribers are notified once per microtask, however many changes happened. When several registrations share an id, the newest one is visible. Removing it brings back the one it replaced, so two components can register the same id and either can unmount first.

createFuzzySearch()

The built-in search engine: an object with search(query, items) that returns ScoredItem[]. How it scores is on the Search page, together with createMatchSorterSearch and how to write your own engine.

createKeywordEngine(synonyms?, userAliases?)

Synonym expansion and aliases. synonyms is a SynonymMap; userAliases is an optional Map<commandId, string[]>.

import { createKeywordEngine } from 'cmdk-engine'

const keywords = createKeywordEngine({ billing: ['money', 'payment'] })
keywords.expandQuery('money') // ['money', 'billing']
keywords.expandQuery('billing') // ['billing', 'money', 'payment']

Inside React, the provider owns a keyword engine built from config.synonyms; it is reachable as useEngineContext().keywords. An alias added there shows up at the next results update. Adding one does not itself re-render anything.

Access control

This is a UI filter, not a security boundary. Enforce permissions on the server.

Frecency

createFrecencyEngine(options?)

Ranks by frequency and recency. A command's score is count * 2^(-daysSinceLastUse / halfLife), so ten uses yesterday beat a hundred a month ago.

FrecencyOptions also has a storageKey, but only the provider reads it. In the core, pass createLocalStorageFrecencyStorage(key) as storage.

Storage backends

A custom backend implements FrecencyStorage: get(key), set(key, entry), getAll(), clear() and, optionally, delete(key).

createGroupManager(groups?)

Holds the group definitions and groups scored results under them. The rules are on Nested Commands and Groups.

createContextEngine(boostWeight = 0.2)

boost(items, context) adds boostWeight (capped at a score of 1) to each scored command whose scope matches the CommandContext. Commands without a scope are unchanged. The matching rules are under context in the API Reference.

Search history

createSearchHistory(config?) keeps past queries in localStorage; createInMemorySearchHistory(config?) keeps them in memory. Both take a SearchHistoryConfig and return the same methods. The localStorage one reads and writes window.localStorage only, and treats a null value as unavailable.

Translations

createDefaultTranslation() returns the English t function: the string for a known key, or the key itself. getTranslationKeys() lists every key; the table is in the API Reference.

Route helpers

The scanners use these to turn a path into a command. They are exported so your own scanner can match.

defineConfig(config)

Returns its argument, typed as CmdkEngineConfig, so your cmdk-engine.config.ts is type-checked. That is the CLI config, not the provider's CommandEngineConfig. See CLI.