Reference

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 + restart timer on duration│
        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           │
        position/theme/maxVisible default to      │
          inject(GLOBAL_OPTIONS_KEY) when the      │
          matching prop isn't passed explicitly    │
        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(resolver.resolve('./plugin'))
  provide(GLOBAL_OPTIONS_KEY, opts)         → own dist/nuxt/plugin.{js,cjs} entry
  app.component('ToastContainer', …)      addImports()/addComponent() source from
                                             the package's main entry (already built)
                                           css inject

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	The plugin runs during SSR too (it's a universal Nuxt plugin, not client-only) — it's ToastContainer's render that produces no toast HTML on the server, since nothing has flushed yet

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

Accessibility

Feature	Implementation
role="alert" / role="status"	alert for error/warning type or critical priority; status otherwise
aria-live	"assertive" for critical priority (or options.ariaLive override); "polite" otherwise
aria-atomic="true"	Always set on the toast element
tabindex="0"	Only when the toast is closable, has an action, or has an undo button
Escape key	Dismisses the focused toast (only when closable); focus returns to the element that was active before the toast appeared
Close button	aria-label="Close"
Group counter	role="button" + aria-label="Show all (N)"
ToastIcon / ToastProgressBar	aria-hidden="true" (decorative)
<ToastContainer> position wrapper	role="region" + aria-label="Notifications", only while that position has active toasts
Keyboard	Escape to dismiss a focused toast; no other keyboard interaction is built in (the close/action/undo buttons are regular focusable buttons)

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

Comparison

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

Migration

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" />

Development

git clone https://github.com/macrulezru/vue-toast-kit.git
cd vue-toast-kit
npm install
npm run build       # vite build + tsc --emitDeclarationOnly
npm run typecheck   # tsc --noEmit
npm run lint        # eslint --fix
npm test            # vitest run

See Demo for running the interactive demo app.

License

MIT