Toast Kit

npm install vue-toast-kit@latest

01 — Назначение

Когда это пригодится

Показать результат действия, не перебивая пользователя модальным alert() и не пряча его в консоли, которую никто не откроет, — с этого начинается vue-toast-kit.

Результат действия неизвестен заранее

Запрос на сервер может зависнуть, завершиться успехом или ошибкой — вместо того чтобы вручную показывать разные уведомления в каждой ветке кода, один и тот же тост сам переключается между «идёт загрузка», «готово» и «ошибка».

Удаление должно быть обратимым

Один случайный клик по «Удалить» — и данные потеряны навсегда. Уведомление даёт несколько секунд на отмену прямо внутри себя, прежде чем действие подтвердится окончательно.

Одно и то же событие повторяется десятки раз

Синхронизация десяти файлов — не десять всплывающих карточек подряд, а один тост со счётчиком, который разворачивается по клику.

Тосты должны выглядеть как часть продукта

Готовое оформление настраивается под любой бренд без единой лишней строчки стилей, а при необходимости от визуальной части можно отказаться совсем и оставить только логику для собственного дизайна.

02 — Фичи

Коротко о главном

Гибкая дизайн‑система и полная кастомизация

Более 30 CSS-переменных (--vtk-*) управляют цветами, шрифтами, отступами, тенями и анимациями. Встроены светлая, тёмная и системная темы, а также возможность передать объект с токенами напрямую в проп theme компонента ToastContainer. Это позволяет адаптировать внешний вид тостов под любой бренд без переопределения стилей и без использования !important.

Позиционирование, анимации и стек-режим

Шесть предустановленных позиций (top/bottom + left/center/right) с плавными CSS‑анимациями появления и исчезновения (slide + fade) для каждой позиции. Режим стека (Sonner‑style) визуально складывает несколько тостов в стопку, показывая до двух «призрачных» карточек позади активного, которые раскрываются при наведении. Поддержка prefers‑reduced‑motion.

Группировка, иконки, слоты и touch‑взаимодействие

Тосты с одинаковым groupKey сворачиваются в один счётчиком +N, который раскрывается по клику. Встроенные иконки для каждого типа (можно заменить на свой компонент или эмодзи). Полная переопределяемость через слоты: от целого тоста до отдельных частей — иконки, контента, кнопок и прогресс‑бара. Поддержка свайпа для закрытия на тач‑устройствах и RTL‑разметки.

Promise‑API с автопереключением и Undo с прогрессом

toast.promise() автоматически переключает тост из состояния loading в success или error, возвращая исходный промис для await. toast.undo() создаёт тост с анимированной шкалой прогресса и кнопкой отмены: клик по кнопке выполняет onUndo и закрывает тост, истечение таймера подтверждает действие через onAutoClose. Поддерживаются асинхронные колбэки.

Приоритетная очередь, изолированные контексты и SSR

Четыре уровня приоритета (critical, high, normal, low) управляют очередью: высокоприоритетные тосты вытесняют низкоприоритетные при достижении лимита видимых. createToastContext() создаёт изолированные очереди для микро‑фронтендов или отдельных зон. Ядро SSR‑безопасно: тосты, вызванные на сервере, буферизируются и воспроизводятся после монтирования ToastContainer.

Headless-режим и доступность

useToastState() даёт доступ ко всей логике очереди, таймерам и состоянию тостов без единого встроенного элемента разметки — постройте собственный UI, если готовая дизайн-система не подходит. Каждый тост получает правильную ARIA-роль и aria-live, а таймер автозакрытия ставится на паузу при наведении, потере фокуса и уходе вкладки в фон.

03 — Быстрый пример

Как это работает

Один вызов — три состояния тоста

toast.promise сам переключает тост из loading в success или error по результату промиса и возвращает тот же промис — await продолжает работать как обычно.

promise.ts
import { toast } from 'vue-toast-kit'

await toast.promise(
  fetch('/api/deploy').then((r) => r.json()),
  {
    loading: 'Deploying…',
    success: 'Deployed successfully!',
    error: 'Deployment failed',
  },
)

// One call, three states — the toast flips from loading to success/error
// on its own, and the original promise is still returned so you can await it.

Удаление с окном на отмену, а не бесповоротно

toast.undo показывает таймер с прогресс-баром — реальное действие (permanentlyDelete) происходит только когда время вышло, а пользователь не нажал «Восстановить».

undo.ts
import { toast } from 'vue-toast-kit'

function deleteFile(id: string) {
  markForDeletion(id)

  toast.undo(`File "${fileName}" deleted`, {
    undo: {
      label: 'Restore',
      duration: 6000,
      onUndo: () => {
        restoreFile(id)
        toast.success('File restored')
      },
    },
    onAutoClose: () => permanentlyDelete(id),
  })
}

// A countdown progress bar gives the user a real window to change their
// mind — the delete only actually happens once the timer runs out unanswered.

Одинаковые тосты схлопываются в один

Тосты с общим groupKey превращаются в один со счётчиком «+N» — при закрытии лидера следующий сам занимает его место, экран не забивается однотипными уведомлениями.

grouping.ts
import { toast } from 'vue-toast-kit'

// All three calls produce one visible toast, with a "+2" counter
toast.info('New message from Alice', { groupKey: 'messages' })
toast.info('New message from Bob', { groupKey: 'messages' })
toast.info('New message from Carol', { groupKey: 'messages' })

// The leader (first in the group) stays visible; when it's dismissed, the
// next toast in the group takes over automatically.