Composable

Options and return values of useCommandPalette, plus the smaller composables it is built from.

useCommandPalette(options)

import { useCommandPalette } from 'vue-cmdk-palette'

const palette = useCommandPalette({ commands, scopes, onSelect: (command) => console.log(command.id) })

Options marked “ref or getter” accept a plain value, a ref, or a getter function, and stay reactive.

option	type	notes
`commands`	`Command[]`, ref or getter	Required.
`scopes`	`Scope[]`, ref or getter
`groupOrder`	`string[]`, ref or getter	Heading order for the empty query.
`maxResults`	`number`, ref or getter	Default `40`.
`filter`	`FilterFn` or a ref of one	A getter isn’t accepted here, since a filter is itself a function.
`recents`	`RecentsOptions \| boolean`, ref or getter	Default `true`.
`quickSelect`	`boolean`, ref or getter	Default `true`.
`labels`	`Partial<PaletteLabels>`, ref or getter
`query`	`Ref<string>`	Bring your own query state, for example from `defineModel`.
`navigate`	`(href) => void`	Router hook for `link` commands.
`onSelect`	`(command, mode) => void`
`onError`	`(error, command) => void`
`onClose`	`() => void`	Called when the palette asks to close.
`onNoResults`	`(query, scope) => void`	A query matched nothing for 500 ms, or at close. Once per query.

State

key	type	notes
`query`	`Ref<string>`	Writable.
`scope`	`Ref<string \| null>`	The chosen chip. Writable. `null` is “All”.
`activeScope`	`ComputedRef<string \| null>`	The scope in force, which a typed prefix may override.
`scopes`	`ComputedRef<Scope[]>`	Chips to draw: none on child pages.
`pages`	read-only ref of open pages	Each entry has `command` and `items`.
`currentPage`	`ComputedRef`	The open page, or `undefined` at the root.
`loading`	read-only `Ref<boolean>`	A page loader is pending.
`list`	`ComputedRef<PaletteList>`	`groups`, `rows`, `matched`, `counts`, `total`, `needle`.
`reachable`	`ComputedRef<RankedRow[]>`	Enabled rows in drawn order.
`selected`	`ComputedRef<RankedRow \| undefined>`
`labels`	`ComputedRef<PaletteLabels>`	Defaults merged with yours.
`placeholder`	`ComputedRef<string>`	Changes on pages that set one.
`breadcrumb`	`ComputedRef<string[]>`	Labels of the open pages.
`announcement`	`ComputedRef<string>`	Text for a polite live region.
`ids`	`{ field, list, live }`	Element ids used by the getters.

Actions

key	does
`move(step)`	Moves the selection, wrapping.
`moveTo('first' \| 'last')`	Jumps to an end.
`hover(row)`	Selects a row if it’s enabled.
`activate(target, mode?)`	Runs a row or command. Returns a promise.
`narrow(scope)`	Picks a chip.
`cycleScope(step)`	Next or previous chip.
`back()`	Leaves the current page. Returns `false` at the root.
`escape()`	Clears, goes back, or closes. Returns `'cleared'`, `'popped'` or `'closed'`.
`reset()`	Back to the root with an empty query.
`close()`	Resets and calls `onClose`.
`forgetRecent(id)`	Removes one command from recents and saves.
`clearRecents()`	Removes every recent of the current namespace and saves.

isSelected(row), isRecent(row), disabledReason(command), quickSelectDigit(row), onFieldKeydown(event), onContainerKeydown(event), fieldAttrs, listAttrs, rowAttrs(row), groupAttrs(group), chipAttrs(scope), optionId(row) and headingId(group). See Headless for how they fit together.

Smaller composables

These are what the components use internally, exported for headless builds.

composable	does
`useRecents(options)`	Loads, ranks and records recents. Returns `entries`, `enabled`, `record(id)`, `forget(id)`, `clear()`, `resolve(commands)`.
`useHotkey(handler, options?)`	A capture-phase `keydown` listener (on `document` unless `target` is set), removed on unmount.
`useFocusTrap(container, active)`	Keeps Tab inside an element and restores focus when it deactivates.
`useScrollLock(active)`	Sets `overflow: hidden` on `body` while active and restores the old value.
`useCommandPaletteContext()`	In a component rendered inside a palette’s slots, that palette’s composable return. Throws outside one.

Composable

useCommandPalette(options)

State

Actions

Helpers and getters

Smaller composables