useToast

A composable to display toast notifications in your app.

Usage

Use the auto-imported useToast composable to display Toast notifications.

<script setup lang="ts">
const toast = useToast()
</script>
  • The useToast composable uses Nuxt's useState to manage the toast state, ensuring reactivity across your application.
  • A maximum of 5 toasts are displayed at a time. When adding a new toast that would exceed this limit, the oldest toast is automatically removed.
  • When removing a toast, there's a 200ms delay before it's actually removed from the state, allowing for exit animations.
Make sure to wrap your app with the App component which uses our Toaster component which uses the ToastProvider component from Reka UI.
Learn how to customize the appearance and behavior of toasts in the Toast component documentation.

API

useToast()

The useToast composable provides methods to manage toast notifications globally.

add()

add(toast: Partial<Toast>): Toast

Adds a new toast notification.

Parameters

toast
Partial<Toast> required
A partial Toast object with the following properties:
title
string
The title displayed in the toast.
description
string
The description displayed in the toast.
icon
string
The icon displayed in the toast.
avatar
AvatarProps
The avatar displayed in the toast. See Avatar.
color
string
The color of the toast.
orientation
'horizontal' | 'vertical'
The orientation between the content and the actions. Defaults to vertical.
close
boolean | ButtonProps
Customize or hide the close button (with false value). Defaults to true.
closeIcon
string
The icon displayed in the close button.
actions
ButtonProps[]
The actions displayed in the toast. See Button.
progress
boolean | ProgressProps
Customize or hide the progress bar (with false value). Defaults to true.
duration
number
The duration in milliseconds before the toast auto-closes. Can also be set globally on the App component.
onClick
(toast: Toast) => void
A callback function invoked when the toast is clicked.
onUpdateOpen
(open: boolean) => void
A callback function invoked when the toast open state changes. Useful to perform an action when the toast closes (expired or dismissed).

::

::

Returns: The complete Toast object that was added.

<script setup lang="ts">
const toast = useToast()

function showToast() {
  toast.add({
    title: 'Success',
    description: 'Your action was completed successfully.',
    color: 'success'
  })
}
</script>

update()

update(id: string | number, toast: Partial<Toast>): void

Updates an existing toast notification.

Parameters

id
string | number required
The unique identifier of the toast to update.
toast
Partial<Toast> required
A partial Toast object with the properties to update.
<script setup lang="ts">
const toast = useToast()

function updateToast(id: string | number) {
  toast.update(id, {
    title: 'Updated Toast',
    description: 'This toast has been updated.'
  })
}
</script>

remove()

remove(id: string | number): void

Removes a toast notification.

Parameters

id
string | number required
The unique identifier of the toast to remove.
<script setup lang="ts">
const toast = useToast()

function removeToast(id: string | number) {
  toast.remove(id)
}
</script>

clear()

clear(): void

Removes all toast notifications.

<script setup lang="ts">
const toast = useToast()

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

toasts

toasts: Ref<Toast[]>

A reactive array containing all current toast notifications.

<script setup lang="ts">
const { toasts } = useToast()
</script>

<template>
  <div>
    <pre>{{ toasts }}</pre>
  </div>
</template>

useOverlay

A composable to programmatically control overlays.