Advanced Usage

Event emitter

Subscribe to queue events for analytics integration (Sentry, Amplitude, etc.). All listeners return an unsubscribe function.

import { getOrCreateGlobalContext } from 'vue-toast-kit'

const queue = getOrCreateGlobalContext().queue

const off = queue.onAdd((item) => {
  analytics.track('toast_shown', { type: item.options.type, message: item.message })
})

queue.onDismiss((id) => {
  analytics.track('toast_dismissed', { id })
})

queue.onUpdate((id, partial) => {
  analytics.track('toast_updated', { id, ...partial })
})

// Unsubscribe when done:
off()

Rate limiting & localStorage persist

import { createToastContext } from 'vue-toast-kit'

// Max 3 toasts per second; extras are silently dropped
const ctx = createToastContext({ rateLimit: 3, rateLimitWindowMs: 1000 })

// Restore toasts with persist:true after page reload
const ctx2 = createToastContext({ persistStorage: true })

Or configure globally via the plugin:

app.use(VueToastPlugin, {
  rateLimit: 5,
  persistStorage: true,
})

Mark individual toasts as persistent:

toast.info('Maintenance window tonight', { persist: true, duration: 0 })
// This toast survives a page reload

Testing utilities

import { createMockToast, mockUseToast } from 'vue-toast-kit/testing'

// In a Vitest / Jest test:
describe('MyComponent', () => {
  it('calls toast.success on save', async () => {
    const mockToast = mockUseToast()
    vi.mock('vue-toast-kit', () => ({ useToast: () => mockToast }))

    // render component, trigger save…

    expect(mockToast.success).toHaveBeenCalledWith('Saved!')
  })
})

// Create a minimal ToastItem stub:
const item = createMockToast({
  message: 'Upload complete',
  options: { type: 'success', duration: 3000 },
})