Integrations & Testing

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

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

app.use(VCommandPalettePlugin) // default instance
app.use(createCommandPalette({ name: 'sidebar', hotkey: ['$mod', 'j'] }))

<template>
  <!-- default -->
  <CommandPalette />
  <!-- sidebar -->
  <CommandPalette name="sidebar" placeholder="Search the sidebar…" />
</template>

Target a specific instance from composables via the name argument:

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

Nuxt

Add to nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['@macrulez/vue-command-palette/nuxt'],
})

Options are read from runtimeConfig.public.vCommandPalette. Configure in nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['@macrulez/vue-command-palette/nuxt'],
  runtimeConfig: {
    public: {
      vCommandPalette: {
        hotkey: ['$mod', 'k'],
        persistRecent: true,
        maxRecent: 5,
      },
    },
  },
})

The Nuxt module installs the plugin automatically. useCommandPalette, useRegisterGroup, and useRegisterCommands are available in all components without explicit imports (if using @nuxt/eslint with auto-imports enabled).

Testing utilities

import { createPaletteContext, PaletteProvider } from '@macrulez/vue-command-palette/testing'

createPaletteContext

Creates a fully isolated palette context — no real DOM, no plugin, no localStorage side-effects:

import { createPaletteContext } from '@macrulez/vue-command-palette/testing'
import { mount } from '@vue/test-utils'
import { describe, it, expect, vi } from 'vitest'
import MyComponent from './MyComponent.vue'

describe('MyComponent', () => {
  it('executes the command', async () => {
    const performFn = vi.fn()

    const { provide, isOpen, query, store } = createPaletteContext({
      commands: [{ id: 'test-cmd', label: 'Test Command', perform: performFn }],
    })

    const wrapper = mount(MyComponent, {
      global: { provide },
    })

    // Interact
    query.value = 'test'
    await wrapper.find('[data-testid="item"]').trigger('click')

    expect(performFn).toHaveBeenCalledOnce()
  })
})

PaletteProvider

A wrapper component that provides context to its slot children — useful for component tree tests:

import { PaletteProvider } from '@macrulez/vue-command-palette/testing'
import { mount } from '@vue/test-utils'

const wrapper = mount(PaletteProvider, {
  props: {
    commands: [{ id: 'cmd', label: 'My Command', perform: vi.fn() }],
    groups: [],
  },
  slots: {
    default: MyConsumerComponent,
  },
})

createPaletteContext options

Option	Type	Default	Description
commands	Command[]	[]	Commands to pre-register (no group)
groups	CommandGroup[]	[]	Groups to pre-register
persistRecent	boolean	false	Enable localStorage persistence
maxRecent	number	5	Recent command limit
maxRecentPerGroup	number	0	Per-group recent limit
localStorageKey	string	'vcp:recent:test'	Key used if persistRecent is true
onOpen	() => void	—	Mock callback for open events
onClose	() => void	—	Mock callback for close events
onError	(err, cmd) => void	—	Mock error handler

Return value

const {
  ctx, // full PaletteContext — pass to inject-based code
  store, // CommandStore — register/search commands directly
  isOpen, // Ref<boolean>
  query, // Ref<string>
  activeIndex, // Ref<number>
  provide, // Record for Vue Test Utils `global: { provide }`
} = createPaletteContext(options)