Справочник

Типы TypeScript

Все публичные типы экспортируются из корня пакета:

import type {
  ToastType, // 'info' | 'success' | 'warning' | 'error' | 'loading' | 'custom'
  ToastPriority, // 'critical' | 'high' | 'normal' | 'low'
  ToastPosition, // 'top-left' | 'top-center' | 'top-right' | 'bottom-*'
  ToastOptions, // Полный объект опций
  ToastItem, // Внутренний реактивный элемент тоста (используется в headless-режиме)
  ToastAction, // { label: string; onClick: () => void }
  ToastUndo, // { label?: string; onUndo: () => void | Promise<void>; duration?: number }
  ToastDesignTokens, // Все ключи CSS-токенов типизированы
  PromiseToastMessages, // { loading, success, error }
  ToastContext, // Изолированный контекст очереди
  GlobalToastOptions, // Опции плагина / модуля
  ToastApi, // Тип возврата useToast()
} from 'vue-toast-kit'

Работа с ToastItem в headless-режиме:

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

function renderCustomToast(t: ToastItem) {
  // t.remaining.value — число 0–1
  // t.isPaused.value  — boolean
  // t.groupCount.value — число
  // t.options.type, t.options.priority и т. д.
}

Типизированное переопределение токенов:

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

Сценарий	Поведение
typeof window === 'undefined'	Вызовы toast() буферизуются в ToastBuffer; browser API не затрагивается
<ToastContainer> монтируется на клиенте	Буфер сбрасывается через 100 мс со всеми ожидающими тостами
ignoreSSR: true	Буфер отключён; тосты, вызванные на SSR, тихо отбрасываются
Гидратация Nuxt	Плагин работает только на клиенте; SSR-рендер не создаёт HTML тостов

// nuxt.config.ts — отключить SSR-буфер, если тосты никогда не вызываются на сервере
vueToastKit: {
  ignoreSSR: true
}

Архитектура

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

Размер бандла и peer-зависимости

Точка входа	Размер (gzip)	Peer-зависимости
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

Поставляется как tree-shakeable ESM (vue-toast-kit.js) и CommonJS (vue-toast-kit.cjs).

Миграция с vue-toastification / vue-sonner

Таблица совместимости API

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()
—	—	Очередь приоритетов
—	—	Группировка
—	—	useToastState() headless
—	—	createToastContext()

Миграция с vue-toastification

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

// После
import { useToast } from 'vue-toast-kit'
const toast = useToast()
toast.success('Hello') // позиция задаётся глобально в плагине

Миграция с vue-sonner

toast.success(), toast.error(), toast.promise() и toast.dismiss() идентичны. Единственное отличие — <ToastContainer /> заменяет <Toaster />:

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

<!-- После (vue-toast-kit) -->
<ToastContainer position="bottom-right" />

Лицензия

MIT