API Toast

Базовые тосты

useToast() — основной composable. Возвращает объект ToastApi. Работает внутри и вне компонентов Vue.

const toast = useToast(context?: ToastContext): ToastApi

При вызове без аргументов внутри компонента используется внедрённый контекст (настроенный плагином). При вызове вне компонента используется глобальный синглтон. Передайте ToastContext из createToastContext() для использования изолированной очереди.

Методы

toast()

(message, options?) => id

Показать тост типа info.

toast.success()

(message, options?) => id

Показать тост типа success.

toast.error()

(message, options?) => id

Показать тост типа error (приоритет high по умолчанию).

toast.warning()

(message, options?) => id

Показать тост типа warning.

toast.info()

(message, options?) => id

Показать тост типа info.

toast.loading()

(message, options?) => id

Показать тост типа loading (без авто-закрытия, по умолчанию не закрывается).

toast.custom()

(component, options?) => id

Заменить тело тоста компонентом Vue.

toast.promise()

(promise, messages, options?) => Promise

См. Тосты для промисов.

toast.undo()

(message, options) => id

См. Тосты с отменой.

toast.update()

(id, partial) => void

Слить опции (и опционально сообщение) в существующий тост. Перезапускает таймер авто-закрытия, если partial меняет duration (или undo.duration) и для этого тоста сейчас запущен таймер.

toast.updateMessage()

(id, message) => void

Обновить только текст сообщения, не трогая опции.

toast.dismiss()

(id?) => void

Закрыть тост по id; без id закрывает все.

toast.dismissAll()

(position?) => void

Закрыть все тосты, опционально с фильтром по позиции.

toast.isActive()

(id) => boolean

Проверить, виден ли ещё тост.

toast.pauseAll()

() => void

Поставить на паузу все таймеры.

toast.resumeAll()

() => void

Возобновить все таймеры.

ToastOptions

ToastOptions — второй аргумент, принимаемый каждым вызовом toast().

id

string · по умолчанию: авто

Уникальный id; если тост с таким id уже активен, он обновляется.

type

ToastType · по умолчанию: 'info'

Визуальный стиль; один из info / success / warning / error / loading / custom.

priority

ToastPriority · по умолчанию: 'normal'

Приоритет в очереди; один из critical / high / normal / low.

duration

number · по умолчанию: 4000

Задержка авто-закрытия в мс; 0 = не закрывается сам.

position

ToastPosition · по умолчанию: позиция контейнера

Отрендерить этот тост в конкретной позиции, независимо от пропа position контейнера.

closable

boolean · по умолчанию: true

Показывать кнопку закрытия.

groupKey

string · по умолчанию: —

Группировать тосты с одинаковым ключом в стек.

icon

Component | string | false · по умолчанию: по умолчанию для типа

SVG-компонент, строка эмодзи или false, чтобы скрыть.

action

{ label, onClick } · по умолчанию: —

Дополнительная кнопка действия внутри тоста.

undo

{ label?, onUndo, duration? } · по умолчанию: —

Кнопка отмены с таймером; см. Тосты с отменой.

onClose

() => void · по умолчанию: —

Вызывается при закрытии тоста (по любой причине).

onAutoClose

() => void · по умолчанию: —

Вызывается только при истечении таймера.

pauseOnHover

boolean · по умолчанию: true

Ставить таймер на паузу при наведении курсора.

pauseOnFocusLoss

boolean · по умолчанию: true

Ставить таймер на паузу, когда вкладка уходит в фон.

swipeToDismiss

boolean · по умолчанию: true

Разрешить свайп влево / вправо для закрытия на сенсорных устройствах.

persist

boolean · по умолчанию: false

Восстанавливать из localStorage после перезагрузки (только для тостов без коллбэков).

component

Component · по умолчанию: —

Заменить всё тело тоста компонентом Vue.

componentProps

Record<string, unknown> · по умолчанию: —

Пропы, передаваемые в component.

ariaLive

'assertive' | 'polite' · по умолчанию: авто

Переопределить автоматическое значение aria-live.

theme

'light' | 'dark' | 'system' | ToastDesignTokens · по умолчанию: —

Тема или переопределение токенов для конкретного тоста.

Примеры

Все типы тостов:

toast.info('Sync complete')
toast.success('File uploaded')
toast.warning('Disk almost full (92 %)')
toast.error('Connection refused')
toast.loading('Fetching data…')

Кастомная длительность и позиция:

toast.success('Copied to clipboard', {
  duration: 2000,
  position: 'top-center',
})

С кнопкой действия:

toast.info('New message from Alex', {
  action: {
    label: 'Open',
    onClick: () => router.push('/messages'),
  },
})

Иконка-эмодзи:

toast.success('Backup complete', { icon: '💾' })

Не закрывается сам до ручного закрытия:

const id = toast.error('Server is down', { duration: 0, closable: true })
// Позже:
toast.dismiss(id)

Обновление существующего тоста:

const id = toast.loading('Uploading…')
// Обновить только сообщение (без изменения опций):
toast.updateMessage(id, 'Processing…')
// Или обновить сообщение + опции вместе:
toast.update(id, { message: 'Almost done…', duration: 3000 })

Насыщенный контент через компонент Vue:

import RichCard from './RichCard.vue'

toast.custom(RichCard, {
  componentProps: { title: 'Hello', body: 'World' },
  duration: 0,
  closable: true,
})

Тосты для промисов

toast.promise() — автоматически переключает тост loading на success или error в зависимости от результата промиса. Возвращает исходный промис, чтобы вы могли сделать await.

toast.promise<T>(
  promise: Promise<T>,
  messages: PromiseToastMessages<T>,
  options?: ToastOptions,
): Promise<T>

PromiseToastMessages

loading

string

Сообщение, пока промис ожидает выполнения.

success

string | (data: T) => string

Сообщение при разрешении; получает разрешённое значение.

error

string | (err: unknown) => string

Сообщение при отклонении; получает ошибку.

Примеры

Статические сообщения:

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

Динамические сообщения из данных / ошибки:

const user = await toast.promise(fetchUser(id), {
  loading: 'Loading user…',
  success: (u) => `Welcome, ${u.name}!`,
  error: (e) => `Could not load user: ${(e as Error).message}`,
})

В действии Pinia:

// stores/files.ts
import { toast } from 'vue-toast-kit'

export const useFileStore = defineStore('files', {
  actions: {
    async upload(file: File) {
      return toast.promise(uploadAPI(file), {
        loading: `Uploading ${file.name}…`,
        success: (res) => `${res.name} uploaded (${res.size} KB)`,
        error: (e) => `Upload failed: ${(e as Error).message}`,
      })
    },
  },
})

reject промиса выбрасывается заново после обновления тоста, так что ваш try / catch или .catch() по-прежнему срабатывает нормально.

Тосты с отменой

toast.undo() — создаёт тост со счётчиком обратного отсчёта в виде прогресс-бара. Когда пользователь кликает по кнопке отмены, вызывается onUndo(), и тост немедленно закрывается. Когда таймер истекает, тост закрывается молча (действие подтверждено).

toast.undo(message: string, options: ToastOptions & {
  undo: {
    onUndo: () => void | Promise<void>
    label?:   string   // default: 'Undo'
    duration?: number  // ms, default: 5000
  }
}): string

Примеры

Удаление с отменой:

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),
  })
}

Архивирование письма:

toast.undo('Email archived', {
  icon: '📨',
  undo: {
    onUndo: () => moveToInbox(emailId),
  },
})

Асинхронная отмена:

toast.undo('Record deleted', {
  undo: {
    onUndo: async () => {
      await api.restore(recordId)
      toast.success('Record restored!')
    },
  },
})