Skip to main content
The useToast composable provides a programmatic way to manage toast notifications in your application. It returns methods to add, update, remove, and clear toasts.

Usage

<script setup>
const toast = useToast()

function saveData() {
  // Save logic here
  toast.add({
    title: 'Success',
    description: 'Your changes have been saved',
    color: 'success',
    icon: 'i-lucide-check-circle'
  })
}
</script>

Return Value

The useToast() composable returns an object with the following properties and methods:
toasts
Ref<Toast[]>
Reactive array of all current toast notifications.
add
(toast: Partial<Toast>) => Toast
Add a new toast notification. Returns the created toast object with its generated ID.
update
(id: string | number, toast: Omit<Partial<Toast>, 'id'>) => void
Update an existing toast by its ID.
remove
(id: string | number) => void
Remove a toast by its ID.
clear
() => void
Clear all toast notifications.

Toast Interface

interface Toast {
  id: string | number
  title?: string | VNode
  description?: string | VNode
  icon?: string
  avatar?: AvatarProps
  color?: 'primary' | 'secondary' | 'success' | 'info' | 'warning' | 'error' | 'neutral'
  duration?: number
  close?: boolean | Omit<ButtonProps, LinkPropsKeys>
  closeIcon?: string
  actions?: ButtonProps[]
  progress?: boolean | Pick<ProgressProps, 'color' | 'ui'>
  orientation?: 'vertical' | 'horizontal'
  open?: boolean
  onClick?: (toast: Toast) => void
  onClose?: () => void
  onOpenChange?: (open: boolean) => void
}

Examples

Basic Toast

<script setup>
const toast = useToast()

toast.add({
  title: 'Hello World',
  description: 'This is a basic toast notification'
})
</script>

Success Toast

<script setup>
const toast = useToast()

toast.add({
  title: 'Success',
  description: 'Operation completed successfully',
  color: 'success',
  icon: 'i-lucide-check-circle',
  duration: 3000
})
</script>

Error Toast

<script setup>
const toast = useToast()

toast.add({
  title: 'Error',
  description: 'Something went wrong. Please try again.',
  color: 'error',
  icon: 'i-lucide-circle-x',
  duration: 5000
})
</script>

Toast with Actions

<script setup>
const toast = useToast()

toast.add({
  title: 'File uploaded',
  description: 'Your file has been uploaded successfully',
  color: 'success',
  actions: [
    {
      label: 'View',
      onClick: () => {
        console.log('View clicked')
      }
    },
    {
      label: 'Dismiss',
      color: 'neutral',
      variant: 'ghost',
      onClick: () => {
        console.log('Dismissed')
      }
    }
  ]
})
</script>

Update Toast

<script setup>
const toast = useToast()

const loadingToast = toast.add({
  id: 'upload-toast',
  title: 'Uploading...',
  description: 'Please wait while we upload your file',
  color: 'info',
  duration: Infinity
})

// Later, update the toast
setTimeout(() => {
  toast.update(loadingToast.id, {
    title: 'Upload complete',
    description: 'Your file has been uploaded',
    color: 'success',
    duration: 3000
  })
}, 2000)
</script>

Remove Toast

<script setup>
const toast = useToast()

const myToast = toast.add({
  title: 'This will disappear',
  description: 'Click the button to remove this toast'
})

function removeToast() {
  toast.remove(myToast.id)
}
</script>

Clear All Toasts

<script setup>
const toast = useToast()

function clearAllToasts() {
  toast.clear()
}
</script>

Toast with Avatar

<script setup>
const toast = useToast()

toast.add({
  title: 'New message',
  description: 'You have a new message from John Doe',
  avatar: {
    src: '/avatars/john.jpg',
    alt: 'John Doe'
  },
  duration: 5000
})
</script>

Horizontal Orientation

<script setup>
const toast = useToast()

toast.add({
  title: 'Settings saved',
  description: 'Your preferences have been updated',
  orientation: 'horizontal',
  color: 'success'
})
</script>

Custom Duration

<script setup>
const toast = useToast()

// Persist indefinitely
toast.add({
  title: 'Important notice',
  description: 'This will stay until manually closed',
  duration: Infinity
})

// Custom duration in milliseconds
toast.add({
  title: 'Quick message',
  duration: 1000
})
</script>

Configuration

The maximum number of toasts displayed at once can be configured using the injection key:
<script setup>
import { provide } from 'vue'
import { toastMaxInjectionKey } from '#ui'

// Limit to 3 toasts
provide(toastMaxInjectionKey, ref(3))
</script>
By default, a maximum of 5 toasts are displayed. When the limit is reached, the oldest toast is removed to make room for the new one.

TypeScript

import type { Toast } from '#ui'
import { useToast } from '#ui'

const toast = useToast()

const myToast: Toast = toast.add({
  title: 'TypeScript example',
  description: 'Fully typed toast notifications'
})

Build docs developers (and LLMs) love