VueCraft NPM

Palette State ​

useCommandPalette() — composable that exposes the global palette state and all control functions. Must be called inside a component tree where VCommandPalettePlugin is installed. Pass an instance name — useCommandPalette('sidebar') — to target a named instance.

ts
import { useCommandPalette } from '@macrulez/vue-command-palette'

const palette = useCommandPalette()

State ​

isOpen ​

Readonly<Ref<boolean>>

Whether the palette is currently open.

query ​

Ref<string>

The current search input. Writable — set it to change the query programmatically.

results ​

ComputedRef<SearchResult[]>

The current search results for query.

activeIndex ​

Ref<number>

Index of the keyboard-selected result.

history ​

Readonly<Ref<Array<{ paletteId: string; query: string; activeIndex: number }>>>

Breadcrumb stack for nested palettes/pages — one entry per level pushed by open(paletteId).

loadingCommandId ​

Readonly<Ref<string | null>>

ID of the command currently running its perform(), or null.

colorTheme ​

Ref<'light' | 'dark' | 'system'>

The active color theme — see Built-in theme switcher.

pinnedIds ​

Readonly<Ref<string[]>>

IDs of the currently pinned commands, in pin order.

queryHistory ​

Readonly<Ref<string[]>>

Recently submitted queries for the session (most recent first) — see Query history.

Methods ​

open ​

(paletteId?: string) => void

Opens the palette. Pass a command's id to push a sub-palette/page onto the breadcrumb stack instead of resetting to the root.

close ​

() => void

Closes the palette and resets query, activeIndex, and history.

toggle ​

() => void

Opens the palette if closed, closes it if open.

goBack ​

() => void

Pops one level off history, or closes the palette if there is no history.

executeActive ​

() => Promise<void>

Runs the currently keyboard-selected result.

executeCommand ​

(cmd: Command) => Promise<void>

Runs a specific command through the full flow (confirm dialog, sub-palette/page, recent/frecency tracking, loading state).

getRecentCommands ​

() => Command[]

Resolves the recent-commands list to their current Command objects.

getPinnedCommands ​

() => Command[]

Resolves pinnedIds to their current Command objects.

registerCommands ​

(commands: Command[]) => () => void

Registers commands with no group header. Returns an unregister function. Prefer useRegisterCommands inside a component — it unregisters automatically on unmount.

registerGroup ​

(group: CommandGroup) => () => void

Registers a full command group. Returns an unregister function. Prefer useRegisterGroup inside a component.

addRecent ​

(id: string) => void

Manually adds a command ID to the recent-commands list.

isPinned ​

(id: string) => boolean

Whether the given command ID is pinned.

pin ​

(id: string) => void

Pins a command.

unpin ​

(id: string) => void

Unpins a command.

togglePin ​

(id: string) => void

Pins the command if unpinned, unpins it if pinned.

Programmatic control ​

ts
const { open, close, toggle } = useCommandPalette()

open() // open the palette
close() // close and reset state
toggle() // toggle open/close

// Push a sub-palette (breadcrumb navigation)
open('parent-command-id')