VueCraft NPM

Vue Plugin ​

VCommandPalettePlugin — sets up the global command store, keyboard listener, and reactive state for a palette instance.

ts
app.use(VCommandPalettePlugin, options)

Options ​

PaletteOptions

name ​

string · default: 'default'

Instance name — see Multiple instances.

hotkey ​

string[] · default: ['$mod', 'k']

Key combination to toggle the palette.

colorTheme ​

'light' | 'dark' | 'system' · default: 'system'

Initial color theme of the palette.

SearchFn · default: built-in fuzzy search

Custom search strategy — see Custom search strategy.

searchNested ​

boolean · default: true

Surface nested subCommands in search results with breadcrumb context.

showDisabled ​

boolean · default: false

Show disabled commands (greyed, non-executable, demoted) instead of hiding them.

frecency ​

boolean · default: false

Boost frequently & recently used commands in the ranking — see Frecency.

onSearch ​

(query: string) => Command[] | Promise<Command[]> · default: —

Plugin-level async data source merged into every query — see Async search.

bindShortcuts ​

boolean · default: false

Auto-register each command's shortcut as a global hotkey.

persistRecent ​

boolean · default: true

Persist recent commands to localStorage.

maxRecent ​

number · default: 5

Maximum total recent commands stored.

maxRecentPerGroup ​

number · default: 0

Max recent per group (0 = unlimited).

localStorageKey ​

string · default: 'vcp:recent'

Key used in localStorage.

onOpen ​

() => void · default: —

Called every time the palette opens.

onClose ​

() => void · default: —

Called every time the palette closes.

onError ​

(err: unknown, command: Command) => void · default: —

Called when perform() throws.

onHighlight ​

(command: Command | null) => void · default: —

Called when the keyboard-active command changes (previews/analytics).

Example with all options ​

ts
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}"`)
  },
})

Multiple instances ​

Run several independent palettes on one app — e.g. a global command bar plus a sidebar search — each with its own hotkey, commands and state. Use createCommandPalette() for every instance beyond the default (it returns a fresh plugin object so Vue's app.use de-duplication doesn't skip it).

ts
import { VCommandPalettePlugin, createCommandPalette } from '@macrulez/vue-command-palette'

app.use(VCommandPalettePlugin) // default instance
app.use(createCommandPalette({ name: 'sidebar', hotkey: ['$mod', 'j'] }))
vue
<template>
  <!-- default -->
  <CommandPalette />
  <!-- sidebar -->
  <CommandPalette name="sidebar" placeholder="Search the sidebar…" />
</template>

Target a specific instance from composables via the name argument:

ts
const sidebar = useCommandPalette('sidebar')
useRegisterCommands([/* … */], 'sidebar')
useRegisterGroup({/* … */}, 'sidebar')

$mod key ​

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

ts
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