Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Overlays

Toast

Brief, non-blocking notifications for actions and status updates.

Last changed in version 0.14.2: Improve keyboard navigation, action feedback, and selected colors across Vue components.

Interactive showcase

Install

Run in your project
bunx --bun @getweini/cli@latest add toast

Start with this example

Import the files copied by the install command, then place the component in your Vue template. The text and values in the example belong to your app; change them to fit your task.

Vue
<script setup lang="ts">
import Button from './components/ui/button/Button.vue'
import ToastProvider from './components/ui/toast/ToastProvider.vue'
import ToastViewport from './components/ui/toast/ToastViewport.vue'
</script>

<template>
  <ToastProvider
    v-slot="{ toast }"
    :messages="{ dismiss: 'Dismiss notification', viewportLabel: 'Notifications' }"
  >
    <Button
      @click="toast.success('Project saved', {
      description: 'Your changes are available to the team.',
    })"
    >
      Save project
    </Button>
    <ToastViewport position="bottom-right" />
  </ToastProvider>
</template>

The newest toast appears at the bottom of a stack. Hover or focus the stack to reveal older notifications. Set the visible limit to control how many can appear at once.

When to use it

Save confirmation

Announce completion after an asynchronous save without interrupting the current task.

Recoverable failure

Keep an error visible and offer a retry action when recovery is possible.

More examples

Mount the notification region

Put one provider and viewport near the app root.

Mount the notification region
<script setup lang="ts">
import ToastProvider from './components/ui/toast/ToastProvider.vue'
import ToastViewport from './components/ui/toast/ToastViewport.vue'

const messages = { dismiss: 'Dismiss notification', viewportLabel: 'Notifications' }
</script>
<template>
  <ToastProvider :messages="messages">
    <p>Your application content stays inside the provider.</p>
    <ToastViewport position="bottom-right" />
  </ToastProvider>
</template>

Report a result

Call useToast from a descendant of ToastProvider.

Report a result
<script setup lang="ts">
import Button from './components/ui/button/Button.vue'
import { useToast } from './components/ui/toast/useToast'

const toast = useToast()
async function save() {
  try {
    await fetch('/api/project', { method: 'POST' })
    toast.success('Project saved')
  } catch {
    toast.error('Could not save the project', { duration: 0 })
  }
}
</script>
<template>
  <Button @click="save">Save project</Button>
</template>

Complete API

Every public prop, model, event, slot, and exposed member of the installed Vue parts is listed below. “Not set” means you can leave that value out; “Required” means you must provide it. Native HTML attributes also work where the component uses a native element.

ToastProvider

Complete API for ToastProvider
NameType or signatureDefaultWhat it does
durationpropnumber | undefined5000Choose how long this feedback stays visible.
limitpropnumber | undefined5Maximum number of items to show or select.
messagespropToastMessagesRequiredSupply the text this component displays for its built-in actions and states.
defaultslot(props: { toast: ToastApi; }) => unknownRequiredContent shown inside ToastProvider.

ToastViewport

Complete API for ToastViewport
NameType or signatureDefaultWhat it does
positionpropToastPosition | undefined"bottom-right"Choose where this content is placed.
defaultslot((props: { toast: ToastRecord; dismiss: () => void; }) => unknown) | undefinedOptionalContent shown inside ToastViewport.
Public type definitions
Public types
// packages/frameworks/vue/components/toast/types.ts
// ------- TYPES -------

export type ToastId = string
export type ToastVariant = 'default' | 'success' | 'warning' | 'destructive' | 'info'
export type ToastPosition =
  | 'top-left'
  | 'top-center'
  | 'top-right'
  | 'bottom-left'
  | 'bottom-center'
  | 'bottom-right'
export type ToastCloseReason = 'timeout' | 'dismiss' | 'action' | 'limit' | 'programmatic'

export interface ToastAction {
  label: string
  onClick: (id: ToastId) => void | Promise<void>
}

export interface ToastOptions {
  id?: ToastId
  title: string
  description?: string
  variant?: ToastVariant
  duration?: number
  action?: ToastAction
  dismissible?: boolean
  onDismiss?: (reason: ToastCloseReason, id: ToastId) => void
}

export type ToastPresetOptions = Omit<ToastOptions, 'title' | 'variant'>

export type ToastUpdate = Partial<Omit<ToastOptions, 'id'>>

export interface ToastRecord
  extends Omit<ToastOptions, 'id' | 'variant' | 'duration' | 'dismissible'> {
  id: ToastId
  variant: ToastVariant
  duration: number
  dismissible: boolean
}

export interface ToastMessages {
  dismiss: string
  viewportLabel: string
}

export interface ToastProviderProps {
  duration?: number
  limit?: number
  messages: ToastMessages
}

export interface ToastViewportProps {
  position?: ToastPosition
}

export interface ToastApi {
  (options: ToastOptions): ToastId
  success: (title: string, options?: ToastPresetOptions) => ToastId
  warning: (title: string, options?: ToastPresetOptions) => ToastId
  error: (title: string, options?: ToastPresetOptions) => ToastId
  info: (title: string, options?: ToastPresetOptions) => ToastId
  update: (id: ToastId, options: ToastUpdate) => void
  dismiss: (id: ToastId) => void
  dismissAll: () => void
}

Implementation notes

  • Set duration to 0 to prevent automatic expiry.
  • The provider limits visible notifications and queues overflow without losing alerts.
  • Use an existing ID with toast.update or a creation call to update rather than duplicate a notification.

Accessibility and localization

  • Provide localized dismiss and viewport labels through messages.
  • Use routine variants for routine outcomes; destructive notifications make assertive announcements.

Source contract and editing guidance