API Reference

Everything you pass to the provider and every hook, plus the command object. The framework-agnostic building blocks are on the Core API page, and the UI and router adapters on Adapters.

CommandItem

A command. Register commands with useCommandRegister, or put them in children of another command. Only id and label are required.

CommandEngineProvider

Initializes the engine and makes it available to every hook and adapter below it. It takes children and an optional config prop of type CommandEngineConfig. Every option is optional.

Keep the config stable. The engines are rebuilt whenever one of searchEngine, accessControl, accessCheckMode, synonyms, frecency, groups, contextBoostWeight, t or searchHistory changes identity. Define the config once at module scope, or useMemo it, instead of writing an inline object in a component that re-renders. Callbacks, maxResults, context and asyncSources are read live, so they can be inline.

frecency

Commands you use often and recently rank higher. Usage is saved to localStorage and falls back to memory where it is unavailable: during SSR, in sandboxed iframes, when the browser blocks cookies, or when window.localStorage is null or rejects writes. To test storage, the provider writes and removes a cmdk-engine-probe key once when it mounts.

const config = {
  frecency: {
    showRecent: true,
    recentCount: 5,
    recentLabel: 'Recent',
  },
}

To turn frecency off, set enabled: false:

const config = { frecency: { enabled: false } }

searchHistory

Off by default. When enabled, a query is recorded when the user selects a command, and kept in localStorage, or in memory where that is unavailable. The in-memory history keeps the options it was created with until the provider remounts. Read it with useSearchHistory().

context

A command with a scope is boosted while searching when the scope matches the context. A scope entry matches the context path when it equals it or is a parent of it (/billing matches /billing/overview), or when a glob such as /billing/* covers it (below /billing, not /billing itself). It matches the context tags when it equals one of them.

asyncSources New in 0.6

Commands loaded for each query, such as a server-side search. The provider loads every source once per query for all consumers, at the root level only: it debounces, aborts stale requests on query change, close, drill-down and unmount, and reports failures per source in asyncErrors. A failing source never breaks the palette.

import type { AsyncSource } from 'cmdk-engine'

const issueSearch: AsyncSource = {
  id: 'issues',
  load: async (query, { signal }) => {
    const res = await fetch(`/api/issues?q=${encodeURIComponent(query)}`, { signal })
    const issues: { id: string; title: string }[] = await res.json()
    return issues.map((issue) => ({
      id: `issue-${issue.id}`,
      label: issue.title,
      href: `/issues/${issue.id}`,
    }))
  },
  shouldFilter: false, // the server already matched the query
  group: 'Issues',
}

export const config = { asyncSources: [issueSearch] }

• isLoading is true from the moment a trigger passes (debounce included) until every source settles. The adapters show a palette.loading row meanwhile; override it with renderLoading.
• asyncErrors maps a source id to its last error, cleared on that source's next success.
• Loaded items need a non-empty string id and label. Items without them (children included) are dropped, the rest still show, and asyncErrors[id] says so, for example "2 items dropped: missing label". A numeric id counts as a missing id. Other fields are checked too: non-string keywords entries are removed; an object icon, description or group that is not a React element is removed; shortcut and scope keep only their string entries; and an item whose children is not an array becomes a plain item. permissions follow the rules for registered commands: null, undefined and an empty string mean no restriction, a string is one permission, array entries become strings, and any other value hides the item.
• when, permissions and hidden apply to loaded items too. Unfiltered items skip search, frecency, the context boost and maxResults, and their groups come after the local groups, in server order.
• Registered commands win on duplicate ids, then earlier sources. Loaded items are never recorded in frecency.
• load, trigger and debounceMs are read when needed, so an inline config does not restart loads. trigger runs during render (twice under StrictMode in development), so keep it pure and cheap. A trigger that passes on an empty query loads as soon as the provider mounts, even for a palette that has never been opened.

Loaded items are untrusted. Only relative, http(s):, mailto: and tel: hrefs are kept; any other href is removed when the items arrive, children included, so it never reaches window.location or a custom renderItem anchor. For deep links such as myapp://..., return an action, or an allowed href that your onNavigate maps. Only href is filtered, so render labels and descriptions as text, never as HTML.

Selecting a command

select(item), which the adapters call for you, does this in order:

1. If the command has children, open them and stop. Nothing else runs, and it is not reported as a selection.
2. Record frecency (not for loaded items), and the query in search history if it is enabled.
3. Run one handler: the onSelect passed to CommandPalette or to select(); else config.onSelect; else the command's action; else onNavigate(href, item), or window.location.href = href without one.
4. Close the palette and clear the query.

If a handler throws, or returns a rejected promise (an async action, say), the error goes to onSelectError(error, item) when you set it. The palette closes right away and does not wait for an async handler. Without onSelectError, a throw propagates and a rejection stays unhandled, as before.

import type { CommandItem } from 'cmdk-engine'

const config = {
  onSelectError: (error: unknown, item: CommandItem) => {
    console.error(item.label, 'failed', error) // or show a toast
  },
}

Because config.onSelect replaces the default handling, adding one for analytics silently stops every action and href from running. To track selections without replacing anything, use useCommandPaletteEvents below. If you do want one handler for everything, call the default yourself:

import type { CommandItem } from 'cmdk-engine'

const config = {
  onSelect: (item: CommandItem) => {
    console.log('command selected', item.id) // your analytics call
    if (item.action) item.action(item)
    else if (item.href) window.location.assign(item.href)
  },
}

Hooks

All hooks must be called in a component under CommandEngineProvider, and not in the component that renders it.

useCommandPalette()

The main hook: the current results and the controls to drive a palette.

useCommandRegister(commands, deps?)

Registers commands while the component is mounted, and removes them when it unmounts. Register app-wide navigation in a layout that stays mounted, and page commands in the page.

• Without deps, it re-registers whenever a registered field changes: ids, text, hrefs, groups, priority, disabled, hidden, keywords, permissions, access mode, shortcut, scope, text icons, children, or the result of when, which is evaluated on each render, so keep it pure. An action always calls the latest closure, so it never goes stale.
• Element icons and meta are not compared: pass deps when they change. Pass deps, such as [flags.beta], to take control of when it re-registers.

import { useCommandRegister } from 'cmdk-engine/react'

function SettingsCommands({ plan }: { plan: string }) {
  // when is evaluated on each render, so the command appears and disappears with plan
  useCommandRegister([{ id: 'sso', label: 'SSO Settings', when: () => plan === 'enterprise' }])
  return null
}

useFrecency()

Direct access to the frecency engine: recordUsage(id), getScore(id), getRecent(count?) and clear().

useSearchHistory()

getRecent(count?), remove(query) and clear(). Needs searchHistory.enabled to have anything to read.

useCommandContext()

Returns { context, boostWeight }, read-only. To change the context, pass a new config.context to the provider.

useEngineContext(caller?)

The engine singletons, for custom UIs and advanced use: registry, search, keywords, accessFilter, frecency, groupManager, contextEngine, searchHistory, t and the current config. For example, registry.registerMany(commands) registers commands outside a component. It throws outside the provider. The optional caller is the name the error message shows; the built-in hooks pass their own.

usePaletteState(caller?)

The shared UI state, which every palette and shortcut under the provider reads and writes: isOpen, setIsOpen, search, setSearch, activePath and setActivePath. It takes the same optional caller as useEngineContext. It is the light way to open the palette from your own button, without running the results pipeline:

import { usePaletteState } from 'cmdk-engine/react'

function OpenPaletteButton() {
  const { setIsOpen } = usePaletteState()
  return <button onClick={() => setIsOpen(true)}>Search</button>
}

useCommandPaletteEvents(onEvent) New in 0.6

Reports what happens in the palette, for analytics, without any telemetry in the package. Call it once, in any component inside the provider. Without it, nothing is reported. The latest onEvent is always called, so it can be an inline function. An error it throws never breaks the palette: it is rethrown on a timer, where it reaches the console and error trackers.

import { useCommandPaletteEvents } from 'cmdk-engine/react'

function PaletteAnalytics() {
  useCommandPaletteEvents((event) => {
    if (event.type === 'search' && event.resultCount === 0) {
      console.log('no results for', event.query) // your analytics call
    }
  })
  return null
}

search fires for every settled query while the user types, so debounce it before sending it anywhere. New event types may be added in minor releases, so ignore types you do not know. The events are typed as CommandPaletteEvent, exported from cmdk-engine.

Translations

The built-in UI strings go through config.t(key, params?). Pass your own to localize them. getTranslationKeys() lists every key:

A t that returns the key for a key it does not know shows that key as the text, so give every key you use a string. The one exception is palette.list: if t returns its key unchanged (the dictionary[key] ?? key pattern) or an empty string, the list keeps its default name, "Suggestions".

Types

All types are exported from cmdk-engine. Two names are easy to confuse: CommandEngineConfig is the provider's config prop, and CmdkEngineConfig is the CLI config file (cmdk-engine.config.ts).

import type {
  CommandItem,
  CommandRegistry,
  CommandGroup,
  CommandContext,
  CommandPaletteState,
  CommandPaletteEvent,
  CommandEngineConfig, // the provider's config prop
  CmdkEngineConfig, // the CLI config file
  SearchEngine,
  ScoredItem,
  GroupedResult,
  GroupedResults,
  AccessControlProvider,
  AccessCheckMode,
  AsyncSource,
  FrecencyOptions,
  FrecencyEntry,
  FrecencyStorage,
  RecentCommandsConfig,
  SearchHistoryConfig,
  SearchHistoryEntry,
  SynonymMap,
  TranslationFn,
  RouteCommandMeta,
  Sitemap,
  SitemapRoute,
} from 'cmdk-engine'