Toast API

Basic Toasts

useToast() — the main composable. Returns a ToastApi object. Works inside and outside Vue components.

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

When called without arguments inside a component, it uses the injected context (set up by the plugin). When called outside a component it falls back to the global singleton. Pass a ToastContext from createToastContext() to use an isolated queue.

Methods

toast()

(message, options?) => id

Show an info toast.

toast.success()

(message, options?) => id

Show a success toast.

toast.error()

(message, options?) => id

Show an error toast (priority: high by default).

toast.warning()

(message, options?) => id

Show a warning toast.

toast.info()

(message, options?) => id

Show an info toast.

toast.loading()

(message, options?) => id

Show a loading toast (no auto-dismiss, not closable by default).

toast.custom()

(component, options?) => id

Replace the toast body with a Vue component.

toast.promise()

(promise, messages, options?) => Promise

See toast.promise.

toast.undo()

(message, options) => id

See toast.undo.

toast.update()

(id, partial) => void

Merge options (and optionally the message) into an existing toast. Restarts the auto-dismiss timer when partial changes duration (or undo.duration) and a timer is currently running for that toast.

toast.updateMessage()

(id, message) => void

Update only the message text without touching options.

toast.dismiss()

(id?) => void

Close a toast by id; omit id to close all.

toast.dismissAll()

(position?) => void

Close all toasts, optionally filtered by position.

toast.isActive()

(id) => boolean

Check if a toast is still visible.

toast.pauseAll()

() => void

Pause all timers.

toast.resumeAll()

() => void

Resume all timers.

ToastOptions

ToastOptions — the second argument accepted by every toast() call.

id

string · default: auto

Unique id; if the same id is already active the toast is updated.

type

ToastType · default: 'info'

Visual style; one of info / success / warning / error / loading / custom.

priority

ToastPriority · default: 'normal'

Queue priority; one of critical / high / normal / low.

duration

number · default: 4000

Auto-dismiss delay in ms; 0 = sticky (never auto-closes).

position

ToastPosition · default: container default

Render this toast at a specific position, regardless of the container's position prop.

closable

boolean · default: true

Show the close button.

groupKey

string · default: —

Group toasts with the same key into a stack.

icon

Component | string | false · default: type default

SVG component, emoji string, or false to hide.

action

{ label, onClick } · default: —

Extra action button inside the toast.

undo

{ label?, onUndo, duration? } · default: —

Undo button with timer; see toast.undo.

onClose

() => void · default: —

Called when the toast is closed (any reason).

onAutoClose

() => void · default: —

Called only when the timer expires.

pauseOnHover

boolean · default: true

Pause the timer on mouse enter.

pauseOnFocusLoss

boolean · default: true

Pause the timer when the tab goes to background.

swipeToDismiss

boolean · default: true

Enable swipe left / right to dismiss on touch devices.

persist

boolean · default: false

Restore from localStorage after reload (only for toasts without callbacks).

component

Component · default: —

Replace the entire toast body with a Vue component.

componentProps

Record<string, unknown> · default: —

Props forwarded to component.

ariaLive

'assertive' | 'polite' · default: auto

Override the automatic aria-live value.

theme

'light' | 'dark' | 'system' | ToastDesignTokens · default: —

Per-toast theme or token overrides.

Examples

All toast types:

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

Custom duration and position:

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

With an action button:

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

Emoji icon:

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

Sticky until manually dismissed:

const id = toast.error('Server is down', { duration: 0, closable: true })
// Later:
toast.dismiss(id)

Update an existing toast:

const id = toast.loading('Uploading…')
// Update message only (no option changes):
toast.updateMessage(id, 'Processing…')
// Or update message + options together:
toast.update(id, { message: 'Almost done…', duration: 3000 })

Rich content via Vue component:

import RichCard from './RichCard.vue'

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

Promise Toasts

toast.promise() — automatically switches a loading toast to success or error based on the promise result. Returns the original promise so you can await it.

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

PromiseToastMessages

loading

string

Message while the promise is pending.

success

string | (data: T) => string

Message on resolve; receives the resolved value.

error

string | (err: unknown) => string

Message on reject; receives the error.

Examples

Static messages:

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

Dynamic messages from data / error:

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

In a Pinia action:

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

The promise reject is re-thrown after updating the toast, so your try / catch or .catch() still fires normally.

Undo Toasts

toast.undo() — creates a toast with a countdown progress bar. When the user clicks the undo button, onUndo() is called and the toast closes immediately. When the timer runs out, the toast closes silently (action confirmed).

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

Examples

Delete with undo:

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

Archive email:

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

Async undo:

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