Toast

updated

Brief messages from a useToast() service — ids to update and remove, promises, groups, and a stacked Toaster that expands on hover.

Demo

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:

MethodDescription
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.
toastsThe current toasts, open and closing.

A toast takes:

FieldDescription
idYour own id, to update the toast or keep it from showing twice.
groupThe Toaster that shows it.
title, descriptionThe text.
colorneutral (the default), primary, success, warning, info or destructive. It colours the icon and the progress bar.
iconA component, or false for none. Each colour but neutral has a default.
loadingShows a spinner instead of the icon and keeps the toast open until an update turns it off.
durationMilliseconds to stay open, Infinity until closed. The toaster's duration otherwise.
closefalse hides the close button.
actionsButtons, each { label, altText?, onClick? }. Pressing one closes the toast.
backgroundAnnounce it politely, for toasts that are not the result of what the user just did.
dataFields of your own, for the toast slot.
onCloseCalled 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

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.

Loading

Promise

Promise

Actions

onClose runs after the toast has gone, so a deletion can wait for it and an Undo can cancel it.

Actions
  • 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".

Positions

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.

Groups

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.

Expand

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.

Custom content

API Reference

Data attributes

data-slotAttributesDescription
toasterdata-side, data-align, data-expand, data-pausedThe fixed region the toasts stack in.
toastdata-state, data-color, data-swipe, data-swipe-directionOne 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.

Changelog

  1. registry 0.23.0

    bc6008b — Exits now use the decelerating curve, like entrances. Collapsible, Accordion, the overlay surfaces (Popover, Select, Menu, Tooltip), Drawer, Toast and InnerLoading used to close on --ease-emphasized-accelerate, which holds still for most of its duration and then snaps shut; closing on --ease-standard-decelerate starts at once and settles gently, so the same duration feels faster. The tokens themselves are unchanged.

  2. core 0.17.0

    bc6008b — Exits now use the decelerating curve, like entrances. Collapsible, Accordion, the overlay surfaces (Popover, Select, Menu, Tooltip), Drawer, Toast and InnerLoading used to close on --ease-emphasized-accelerate, which holds still for most of its duration and then snaps shut; closing on --ease-standard-decelerate starts at once and settles gently, so the same duration feels faster. The tokens themselves are unchanged.

  3. registry 0.22.0

    5c0a1ae — Closing the last toast with the mouse no longer leaves the toaster paused: the next toast's progress bar runs, and in Firefox its timer starts and it closes on time. ToastRecordRoot clears Reka's paused flag when the last toast unmounts, and Toaster clears its own when its list empties.

    a68b4b7 — Toasts stay clickable while a modal Dialog, Drawer or other overlay that blocks outside pointer events is open: a press on a toast's action runs it instead of falling through to the dialog's overlay and closing the dialog.

    d30f753 — A class on Toaster now wins over its built-in styles: w-96, bottom-24 or [--toast-gap:1rem] set the viewport's width, inset and spacing. The toaster's <style> block sits in @layer components instead of outranking every utility.

    73e420f — Toaster renders the ConfigProvider direction as its viewport's dir, so the placement, the dismissing swipe and the progress bar agree: under ConfigProvider dir="rtl" a bottom-end toaster sits at the left edge and swipes left. An app that sets only <html dir="rtl"> without a ConfigProvider now gets a left-to-right toaster (right edge, swipe right, bar shrinking to the left); wrap the app in ConfigProvider dir="rtl".

  4. core 0.16.0

    5c0a1ae — Closing the last toast with the mouse no longer leaves the toaster paused: the next toast's progress bar runs, and in Firefox its timer starts and it closes on time. ToastRecordRoot clears Reka's paused flag when the last toast unmounts, and Toaster clears its own when its list empties.

  5. registry 0.18.0

    779955e — Corners come in three roles: rounded-control-*, rounded-surface-* and rounded-item-*, each scaled from --radius and tunable on its own with --control-radius, --surface-radius and --item-radius, on :root or any element. Every component uses them, and cn() merges them, so a class prop still wins.

    - --control-radius was the Input family's frame variable. It now sets every control, and the frames use --frame-radius. - Nested parts no longer turn square at small radii: the InputGroup button, the InputNumber steppers, the TagsInput chips, the DatePicker trigger and the Toast and Tour close buttons. - Menus, lists, pill tabs, the menubar and the toolbar wrap their corners around their items. Pill tabs are rounder (12/8px at md instead of 8/4px), menus and lists grow by up to 2px, and their rows at sizes xs and xl follow their height. Item sm takes 8px instead of 6.4px.

  6. registry 0.13.0

    93e57a0 — Every size on the control scale is named xs to xl; default and the bare icon are gone. To move over:

    - Button: size="default" becomes size="md", or leave size out; size="icon" becomes size="icon-md". The full set is xs to xl and icon-xs to icon-xl. Toggle, ToggleGroup, ToggleGroupItem, the Toolbar parts, AlertDialogAction, AlertDialogCancel and ToastAction take the same names; Button, Toggle and ToggleGroup default to md, the Toolbar parts keep sm and ToastAction keeps xs. InputGroupButton keeps its own xs, sm, icon-xs and icon-sm, 24 and 32px to fit inside the group, xs by default. Pagination hands its md to Button as it is. Button, Toggle and ToggleGroupItem set data-variant, data-color and data-size even when you leave them at their defaults. - AlertDialogContent: size="default" becomes size="md", still the default; sm is unchanged. The size option of useConfirm's confirm, alert and prompt takes the same names. - Table and DataTable: density becomes size, data-density becomes data-size, and the TableDensity type is now TableSize. sm, md and lg keep their 36, 44 and 52px rows; xs (28px) and xl (60px) are new, and DataTable's virtual row estimates cover them. The cells' padding above and below the text is now --table-cell-py on the table: 8px as before, 3px at xs. At xs, DataTable's sort buttons and expand and group toggles shrink to fit the row. The table-density example is now table-sizes. - DrawerMenu: size takes xs to xl like Menu and reads the control scale, plus room for a thumb. sm, md and lg keep their 40, 48 and 56px rows, padding and icons; xs is 36px and xl 64px. Overriding a --control-* token on :root now resizes DrawerMenu rows as well. - Select and Combobox: the list opens at the trigger's or anchor's size instead of always at md, so <SelectTrigger size="xl"> opens an xl list. size on SelectContent or ComboboxList picks another. Behind an as-child button, set size on ComboboxAnchor to match the button. The Select list now sets its menu variables on SelectContent instead of its viewport, so a class such as [--menu-item-height:2.5rem] on SelectContent reaches the items. - Input, Textarea, InputFloating, SelectTrigger, ComboboxAnchor and Separator set data-size with the default filled in, and the anchor sets data-variant too. With as-child, the anchor leaves the button's own data-variant and data-size alone.

    5af8c25 — With Reka UI 2.11, the toasts in a Toaster ease to their new height again when a toast arrives or closes and when the stack expands, instead of jumping to it. Reka 2.11 measures each toast by setting its inline height to auto, which cut the toast's height transition short. The toast now takes its height from min-height and max-height, which the measuring leaves alone. With Reka UI 2.10 the stack looks and moves as before.

  7. registry 0.6.0

    715f6fc — Components are coloured by tones. A colour is three inputs, --tone, --tone-foreground and --tone-text, set on [data-slot][data-color="<name>"]; core derives --tone-soft, --tone-soft-foreground, --tone-border and --tone-border-subtle from them and registers all seven as tone-* colours, so bg-tone, text-tone-text and the rest work as classes. The --c-* variables are gone: a rule that set --c, --c-fg, --c-soft, --c-soft-fg or --c-edge now sets --tone, --tone-foreground and --tone-text, and drops the rest. Button, Badge, Alert, Toggle, the choice controls and Toast read tones; Toast no longer exports toastAccents.

  8. core 0.5.0

    715f6fc — Components are coloured by tones. A colour is three inputs, --tone, --tone-foreground and --tone-text, set on [data-slot][data-color="<name>"]; core derives --tone-soft, --tone-soft-foreground, --tone-border and --tone-border-subtle from them and registers all seven as tone-* colours, so bg-tone, text-tone-text and the rest work as classes. The --c-* variables are gone: a rule that set --c, --c-fg, --c-soft, --c-soft-fg or --c-edge now sets --tone, --tone-foreground and --tone-text, and drops the rest. Button, Badge, Alert, Toggle, the choice controls and Toast read tones; Toast no longer exports toastAccents.