Composables & Plugin

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.

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

const {
  isOpen, // Readonly<Ref<boolean>>
  query, // Ref<string>
  results, // ComputedRef<SearchResult[]>
  activeIndex, // Ref<number>
  history, // Readonly<Ref<HistoryEntry[]>>
  loadingCommandId, // Readonly<Ref<string | null>>

  open, // (paletteId?: string) => void
  close, // () => void
  toggle, // () => void
  goBack, // () => void — pop history, or close if empty
  executeCommand, // (cmd: Command) => Promise<void>
  executeActive, // () => Promise<void> — run the currently selected result
  getRecentCommands, // () => Command[]
  getPinnedCommands, // () => Command[]
  registerCommands, // (commands: Command[]) => () => void
  registerGroup, // (group: CommandGroup) => () => void
  addRecent, // (id: string) => void
  pin,
  unpin,
  togglePin,
  isPinned, // pinned commands API
  pinnedIds, // Readonly<Ref<string[]>>
  queryHistory, // Readonly<Ref<string[]>>
} = useCommandPalette()

Programmatic control

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')

useRegisterCommands

Registers commands when the component mounts and automatically unregisters them when it unmounts. Commands registered this way have no group header.

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

// In any component setup()
useRegisterCommands([
  {
    id: 'format-doc',
    label: 'Format Document',
    icon: '✨',
    perform: () => formatDocument(),
  },
  {
    id: 'toggle-sidebar',
    label: 'Toggle Sidebar',
    shortcut: ['$mod', 'b'],
    perform: () => sidebar.toggle(),
  },
])

useRegisterGroup

Registers a full command group with a label and priority on mount, unregisters on unmount.

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

useRegisterGroup({
  id: 'editor',
  label: 'Editor',
  priority: 80,
  commands: [
    {
      id: 'editor-format',
      label: 'Format Document',
      description: 'Run Prettier on the current file',
      icon: '✨',
      perform: () => format(),
    },
    {
      id: 'editor-lint',
      label: 'Lint File',
      description: 'Run ESLint and show errors',
      icon: '🔍',
      enabled: () => isFileOpen.value,
      perform: () => lint(),
    },
  ],
})

VCommandPalettePlugin

The Vue plugin that sets up the global command store, keyboard listener, and reactive state.

app.use(VCommandPalettePlugin, options)

Options (PaletteOptions)

Option	Type	Default	Description
name	string	'default'	Instance name (see Multiple instances)
hotkey	string[]	['$mod', 'k']	Key combination to toggle the palette
colorTheme	'light' | 'dark' | 'system'	'system'	Initial color theme of the palette
search	SearchFn	built-in fuzzy	Custom search strategy (see Custom search)
searchNested	boolean	true	Surface nested subCommands in search results with breadcrumb context
showDisabled	boolean	false	Show disabled commands (greyed, non-executable, demoted) instead of hiding them
frecency	boolean	false	Boost frequently & recently used commands in the ranking (see Frecency)
onSearch	(query) => Command[] | Promise<Command[]>	—	Plugin-level async data source merged into every query (see Async search)
bindShortcuts	boolean	false	Auto-register each command's shortcut as a global hotkey
persistRecent	boolean	true	Persist recent commands to localStorage
maxRecent	number	5	Maximum total recent commands stored
maxRecentPerGroup	number	0	Max recent per group (0 = unlimited)
localStorageKey	string	'vcp:recent'	Key used in localStorage
onOpen	() => void	—	Called every time the palette opens
onClose	() => void	—	Called every time the palette closes
onError	(err: unknown, command: Command) => void	—	Called when perform() throws
onHighlight	(command: Command | null) => void	—	Called when the keyboard-active command changes (previews/analytics)

Example with all options

app.use(VCommandPalettePlugin, {
  hotkey: ['$mod', 'k'],
  colorTheme: 'system', // 'light' | 'dark' | 'system'
  persistRecent: true,
  maxRecent: 8,
  maxRecentPerGroup: 2,
  localStorageKey: 'myapp:palette:recent',
  onOpen: () => analytics.track('palette_opened'),
  onClose: () => analytics.track('palette_closed'),
  onError: (err, cmd) => {
    console.error(`Command "${cmd.label}" failed:`, err)
    toast.error(`Failed to run "${cmd.label}"`)
  },
})

$mod key

$mod resolves to Meta (⌘) on macOS and Ctrl on Windows / Linux — use it for portable shortcuts:

hotkey: ['$mod', 'k'] // Cmd+K on Mac, Ctrl+K on Windows
shortcut: ['$mod', 'shift', 'p'] // Cmd+Shift+P on Mac, Ctrl+Shift+P on Windows