Reference

TypeScript types

All public types are exported from the package root:

import type {
  ToastType, // 'info' | 'success' | 'warning' | 'error' | 'loading' | 'custom'
  ToastPriority, // 'critical' | 'high' | 'normal' | 'low'
  ToastPosition, // 'top-left' | 'top-center' | 'top-right' | 'bottom-*'
  ToastOptions, // Full options object
  ToastItem, // Internal reactive toast item (used in headless mode)
  ToastAction, // { label: string; onClick: () => void }
  ToastUndo, // { label?: string; onUndo: () => void | Promise<void>; duration?: number }
  ToastDesignTokens, // All CSS token keys typed
  PromiseToastMessages, // { loading, success, error }
  ToastContext, // Isolated queue context
  GlobalToastOptions, // Plugin / module options
  ToastApi, // Return type of useToast()
} from 'vue-toast-kit'

Working with ToastItem in headless mode:

import type { ToastItem } from 'vue-toast-kit'

function renderCustomToast(t: ToastItem) {
  // t.remaining.value — number 0–1
  // t.isPaused.value  — boolean
  // t.groupCount.value — number
  // t.options.type, t.options.priority, etc.
}

Typed token override:

import type { ToastDesignTokens } from 'vue-toast-kit'

const darkGlass: ToastDesignTokens = {
  colorBg: 'rgba(15, 15, 20, 0.85)',
  colorText: '#f0f0f0',
  borderRadius: '14px',
  shadow: '0 8px 32px rgba(0,0,0,0.6)',
}

SSR compatibility

Scenario	Behaviour
typeof window === 'undefined'	toast() calls are buffered in ToastBuffer; no browser API is touched
<ToastContainer> mounts on the client	Buffer is flushed after 100 ms with all pending toasts
ignoreSSR: true	Buffer is disabled; SSR-fired toasts are discarded silently
Nuxt hydration	Plugin runs client-side only; SSR render produces no toast HTML

// nuxt.config.ts — disable SSR buffer if you never fire toasts on the server
vueToastKit: {
  ignoreSSR: true
}

Architecture

useToast() / toast (singleton)
        │
        ├── buildToastApi(context)
        │     toast(), toast.success/error/warning/info/loading/custom()
        │     toast.promise()   — updates type + restarts timer
        │     toast.undo()      — wraps options.undo
        │     toast.dismiss()   — proxies to queue.dismiss()
        │
        ▼
   ToastContext
        │   addToast()  →  isServer ? ToastBuffer : ToastQueue.add()
        │   dismiss()   →  ToastQueue.dismiss()
        │   update()    →  ToastQueue.update()
        │
        ▼
   ToastQueue                    GroupManager
        active: ToastItem[]  ◄───────────────────┐
        pending: ToastItem[]      add(id, key)    │
        timers: Map<id, UndoTimer>  remove(id, key)│
                                  toggleExpand()  │
        add()  — dedup / preempt / sort pending   │
        remove() — free slot, promote from pending│
        update() — merge options                  │
        dismiss() — calls onClose, remove         │
                                                  │
   UndoTimer                                      │
        setTimeout/setInterval, pause/resume       │
        remaining: number (0–1)  ────────────────►│ ToastItem.remaining.value
        onExpire: () => queue.remove(id)          │
                                                  │
   ToastBuffer (SSR)                              │
        push() — store before window exists       │
        flush() — replay into queue at mount      │
        onFlush() — called by ToastContainer      │
                                                  │
   ToastContainer.vue                             │
        Teleport → body                           │
        TransitionGroup (slide + fade per position)│
        hover → queue.pauseAll() / resumeAll()    │
        visibilitychange → pause/resume           │
        slot: #toast / #toast-icon / …            │
        │                                         │
        └── Toast.vue                             │
              swipe (touch)                       │
              aria role + aria-live               │
              ToastIcon.vue (SVG + spinner)        │
              ToastProgressBar.vue (scaleX)       │
              action / undo buttons               │
              group counter (click → toggleExpand)│

Plugin (VueToastPlugin)                 Nuxt Module
  app.use() → installContext()            defineNuxtModule()
  provide(TOAST_CONTEXT_KEY, ctx)         addPlugin(), addImports()
  app.component('ToastContainer', …)      addComponent(), css inject

Bundle size & peer dependencies

Entry point	Size (gzip)	Peer deps
vue-toast-kit (JS)	~9.2 KB	vue ^3.3
vue-toast-kit/style (CSS)	~2.4 KB	—
vue-toast-kit/nuxt	~0.6 KB	vue ^3.3, @nuxt/kit

Ships as tree-shakeable ESM (vue-toast-kit.js) and CommonJS (vue-toast-kit.cjs).

Migration from vue-toastification / vue-sonner

API compatibility table

vue-toastification	vue-sonner	vue-toast-kit
useToast()	—	useToast()
toast(msg, { type: TYPE.SUCCESS })	toast.success(msg)	toast.success(msg)
toast(msg, { type: TYPE.ERROR })	toast.error(msg)	toast.error(msg)
toast(msg, { type: TYPE.WARNING })	—	toast.warning(msg)
toast(msg, { type: TYPE.INFO })	toast(msg)	toast.info(msg)
toast.loading(msg)	toast.loading(msg)	toast.loading(msg)
POSITION.BOTTOM_RIGHT	—	'bottom-right'
POSITION.TOP_CENTER	—	'top-center'
toast.dismiss(id)	toast.dismiss(id)	toast.dismiss(id)
toast.update(id, opts)	—	toast.update(id, opts)
—	toast.promise()	toast.promise()
—	—	toast.undo()
—	—	Priority queue
—	—	Grouping
—	—	useToastState() headless
—	—	createToastContext()

Migrating from vue-toastification

// Before
import { useToast, TYPE, POSITION } from 'vue-toastification'
const toast = useToast()
toast('Hello', { type: TYPE.SUCCESS, position: POSITION.BOTTOM_RIGHT })

// After
import { useToast } from 'vue-toast-kit'
const toast = useToast()
toast.success('Hello') // position is set globally in the plugin

Migrating from vue-sonner

toast.success(), toast.error(), toast.promise(), and toast.dismiss() are identical. The only difference is that <ToastContainer /> replaces <Toaster />:

<!-- Before (vue-sonner) -->
<Toaster position="bottom-right" />

<!-- After (vue-toast-kit) -->
<ToastContainer position="bottom-right" />

License

MIT