Toast
updatedBrief messages from a useToast() service — ids to update and remove, promises, groups, and a stacked Toaster that expands on hover.
Installation
Usage
Install the service once, next to the app:
// main.ts
import { createApp } from 'vue'
import { createToaster } from '@/components/ui/toast'
import App from './App.vue'
createApp(App).use(createToaster()).mount('#app')
In Nuxt, do the same from a plugin:
// plugins/toaster.ts
import { createToaster } from '@/components/ui/toast'
export default defineNuxtPlugin((nuxtApp) => {
nuxtApp.vueApp.use(createToaster())
})
Put a Toaster in the root component, and add toasts from anywhere below it:
<!-- App.vue -->
<script setup lang="ts">
import { Toaster } from '@/components/ui/toast'
</script>
<template>
<RouterView />
<Toaster />
</template>
<script setup lang="ts">
import { Button } from '@/components/ui/button'
import { useToast } from '@/components/ui/toast'
const toast = useToast()
</script>
<template>
<Button @click="toast.add({ title: 'Saved', color: 'success' })">Save</Button>
</template>
Each app gets its own list of toasts, so on the server one request never sees another's. Outside components — a router guard, an HTTP interceptor, a store — call the object createToaster() returned.
useToast() returns:
| Method | Description |
|---|---|
add(toast) | Shows a toast and returns its id. With the id of a toast already shown, updates that one instead. |
update(id, toast) | Changes the fields given and keeps the rest. A closing toast opens again. |
remove(id) | Closes the toast; it leaves the list once its exit animation ends. |
clear(group?) | Closes the toasts of one group, or every toast. |
promise(promise, { loading, success, error }) | Shows loading until the promise settles, then updates the same toast with success or error — a toast, or a function of the result that returns one. Success is success coloured and error destructive unless they say otherwise. Returns the id. |
toasts | The current toasts, open and closing. |
A toast takes:
| Field | Description |
|---|---|
id | Your own id, to update the toast or keep it from showing twice. |
group | The Toaster that shows it. |
title, description | The text. |
color | neutral (the default), primary, success, warning, info or destructive. It colours the icon and the progress bar. |
icon | A component, or false for none. Each colour but neutral has a default. |
loading | Shows a spinner instead of the icon and keeps the toast open until an update turns it off. |
duration | Milliseconds to stay open, Infinity until closed. The toaster's duration otherwise. |
close | false hides the close button. |
actions | Buttons, each { label, altText?, onClick? }. Pressing one closes the toast. |
background | Announce it politely, for toasts that are not the result of what the user just did. |
data | Fields of your own, for the toast slot. |
onClose | Called once the toast is gone for good — not when it is closed and added again. |
Examples
The examples add their toasts to this site's one Toaster, as your app would. The ones about the toaster itself bring their own, with a group and a corner of their own.
Colours
Loading
A toast updated in place keeps its spot. Its timer starts over when loading or duration changes, so the finished toast stays up for its full time.
Promise
Actions
onClose runs after the toast has gone, so a deletion can wait for it and an Undo can cancel it.
- Budget.xlsx
- Minutes.docx
- Roadmap.pdf
Deleted for good: nothing yet
Positions
start and end follow the reading direction, and so do the swipe that dismisses a toast and its progress bar. The toaster takes the direction from Reka's ConfigProvider and renders it as its own dir; <html dir="rtl"> alone is not read, so a right-to-left app wraps itself in ConfigProvider dir="rtl".
Groups
A toast goes to the Toaster with its group; a toaster without one takes the toasts without one. Here uploads go to a second toaster at the top, and everything else to the app's.
Expand and progress
The stack unfolds while the pointer or focus is on it; expand keeps it unfolded. progress draws each timed toast's timer, which pauses with it.
Custom content
The toast slot replaces what is inside each toast, given the toast with your data. ToastTitle, ToastDescription, ToastAction and ToastClose keep their roles; ToastRow is the default content, to reuse around your own.
API Reference
Toaster
class is also accepted and goes to the viewport.
| Prop | Default | Type and description |
|---|---|---|
| group | — | stringShows only toasts added with this |
| position | "bottom-end" | ToastPositionCorner or edge of the screen: |
| expand | — | booleanLay every toast out in full instead of stacking the older ones behind the newest until the pointer or focus is on them. |
| max | 5 | numberHow many toasts stay open at once; adding one more closes the oldest. |
| duration | 5000 | numberMilliseconds a toast stays open when it sets no |
| progress | — | booleanDraw a bar along the bottom of each timed toast that runs out with its timer. |
| label | "Notification" | stringWhat screen readers call each toast when announcing it. |
| hotkey | ["F8"] | string[]Keys that move focus to the toasts. |
| Slot | Scope and description |
|---|---|
| toast | { toast: Toast; }Replaces the content of each toast, given |
ToastAction
| Prop | Default | Type and description |
|---|---|---|
| altText* | — | stringAnother way to do the same thing, read to screen reader users, who may not reach the button before the toast closes. |
| variant | "soft" | "soft" | "solid" | "subtle" | "outline" | "ghost" | "link" | nullButton variant. |
| color | "neutral" | ButtonColor | (string & {})Button colour. |
| size | "xs" | ButtonSizeButton size. |
| Slot | Scope and description |
|---|---|
| default | {}The label. Pressing the button closes the toast. |
ToastClose
| Slot | Scope and description |
|---|---|
| default | {}The icon, an X by default. |
ToastDescription
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | {}Secondary text under the title. |
ToastRow
| Prop | Default | Type and description |
|---|---|---|
| toast* | — | ToastThe toast to lay out: its icon or spinner, title, description, actions and close button. |
ToastTitle
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | {}The toast's title. |
class is also accepted and goes to the viewport.
Props
- group
stringShows only toasts added with thisgroup. Without it, the toaster shows toasts added without one.- position
"bottom-end" ToastPositionCorner or edge of the screen:top-start,top-center,top-end,bottom-start,bottom-centerorbottom-end.startandendfollow the text direction, and so does the swipe that closes a toast.- expand
booleanLay every toast out in full instead of stacking the older ones behind the newest until the pointer or focus is on them.- max
5 numberHow many toasts stay open at once; adding one more closes the oldest.- duration
5000 numberMilliseconds a toast stays open when it sets nodurationof its own. The timer pauses while the pointer or focus is on the toasts, or the window is in the background.- progress
booleanDraw a bar along the bottom of each timed toast that runs out with its timer.- label
"Notification" stringWhat screen readers call each toast when announcing it.- hotkey
["F8"] string[]Keys that move focus to the toasts.
Slots
- toast
{ toast: Toast; }Replaces the content of each toast, given{ toast }. The toast's surface, place in the stack, swipe and timer stay.
Props
- altText*
stringAnother way to do the same thing, read to screen reader users, who may not reach the button before the toast closes.- variant
"soft" "soft" | "solid" | "subtle" | "outline" | "ghost" | "link" | nullButton variant.- color
"neutral" ButtonColor | (string & {})Button colour.- size
"xs" ButtonSizeButton size.
Slots
- default
{}The label. Pressing the button closes the toast.
Slots
- default
{}The icon, an X by default.
Props
- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Slots
- default
{}Secondary text under the title.
Props
- toast*
ToastThe toast to lay out: its icon or spinner, title, description, actions and close button.
Props
- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Slots
- default
{}The toast's title.
Data attributes
| data-slot | Attributes | Description |
|---|---|---|
| toaster | data-side, data-align, data-expand, data-paused | The fixed region the toasts stack in. |
| toast | data-state, data-color, data-swipe, data-swipe-direction | One toast. |
| toast-content | — | The padded content, measured for the stack. |
| toast-icon | — | The colour's icon, or your own. |
| toast-title | — | The title. |
| toast-description | — | Secondary text. |
| toast-action | — | An action button. |
| toast-close | — | The close button. |
| toast-progress | — | The bar that runs out with the timer. |
Accessibility
Toasts sit in a region labelled "Notifications (F8)"; F8 moves focus to them. Each toast is announced when it appears, assertively unless it is a background one. The timers pause while the pointer or focus is on the toasts and while the window is in the background. Escape closes the toast that has focus and leaves the rest — pressing it elsewhere, to close a dialog for instance, keeps them. altText on an action tells screen reader users another way to do it, since the toast may close before they reach the button.