Motion UIComponentsComponent

Command palette

Motion's fuzzy-filtered Cmd+K launcher choreography on Base UI's Dialog primitive, with a sliding selection highlight.

npx shadcn@latest add @motion/command-palette
MotionScore

API reference

Components

<CommandPalette />

open?

boolean

Controlled open state. Omit for uncontrolled state.

defaultOpen?

boolean = false

Initial open state when uncontrolled. Defaults to false.

onOpenChange?

(open: boolean) => void

Called whenever Base UI requests an open-state change.

items

CommandPaletteItem[]

The commands the palette filters and lists.

groupOrder?

string[]

The order group headers render in; defaults to the items' own first-seen group order. Groups left empty by the current query are dropped.

maxListHeight?

number = 320

Tallest the scrollable result list is allowed to grow before it scrolls internally - how much of the command set is visible at once.

triggerLabel?

string = "Search commands, funnels, cohorts…"

The collapsed trigger bar's placeholder text.

triggerShortcut?

string = "⌘K"

The trigger's trailing shortcut badge glyphs.

inputPlaceholder?

string = "Type a command or search…"

The open dialog input's placeholder.

inputAriaLabel?

string = "Search commands"

The open dialog input's accessible label.

dialogLabel?

string = "Command palette"

The dialog's accessible label.

footerHints?

CommandFooterHint[] = DEFAULT_FOOTER_HINTS

The footer-strip hints. Defaults to navigate / select / close.

renderEmpty?

(query: string) => ReactNode = defaultRenderEmpty

Renders the no-results message; receives the trimmed query.

onSelect?

(item: CommandPaletteItem) => void

Called with the chosen item when a row is selected (click or Enter). The palette closes itself afterwards; wire navigation here.

Hooks

useCommandK

Headless open-state engine for a command palette. Manages the open flag and installs a single window-level Cmd/Ctrl+K listener that toggles it from anywhere on the page (not only while a trigger holds focus - the defining Cmd+K affordance). CommandPalette uses this internally; call it yourself to drive a custom trigger or your own palette surface.

useCommandK(options: UseCommandKOptions): UseCommandKResult

defaultOpen?

boolean = false

Whether the palette starts open. Defaults to false.

open?

boolean

Controlled open state. Omit for uncontrolled state.

onOpenChange?

(open: boolean) => void

Called whenever the open state changes (opened or closed).

Returns

open

boolean

Whether the palette is open.

setOpen

(open: boolean) => void

Set the open state directly.

openPalette

() => void

Open the palette.

closePalette

() => void

Close the palette.

toggle

() => void

Toggle the palette - what the global Cmd/Ctrl+K shortcut fires.

Functions

fuzzyMatch

Subsequence fuzzy match: every character of query must appear, in order, somewhere in target - a genuinely fuzzy filter rather than a plain substring test, so "fnl" still surfaces "Funnels". Both arguments are matched as-is (lower-case them yourself, as commandMatches does).

fuzzyMatch(query: string, target: string): boolean

commandMatches

Whether a command survives the query: its lower-cased label, or any of its keywords, fuzzy-matches the trimmed lower-cased query. An empty query matches everything.

commandMatches(command: CommandPaletteItem, query: string): boolean

id

string

label

string

hint?

string

group?

string

icon?

ComponentType<{ className?: string; "aria-hidden"?: boolean }>

shortcut?

string[]

keywords?

string[]

filterCommandGroups

Filters items by query and buckets the survivors into groups, in groupOrder (falling back to the items' own first-seen group order), dropping any group left empty. This is exactly what CommandPalette shows; call it directly if you filter a remote command source yourself.

filterCommandGroups(items: T[], groupOrder: string[] | undefined, query: string): CommandGroupView<T>[]

nextCommandIndex

Wraps listbox keyboard navigation while keeping an empty result set at zero.

nextCommandIndex(currentIndex: number, resultCount: number, direction: "next" | "previous"): number

Featured in

See the command palette composed into full sections.

Navigation: Command paletteAn example of a Cmd+K command palette with a fuzzy-filtered, keyboard-navigable list and a shared-layout selection highlight in Motion for React.

Related examples