Toast

Installation

npx @yolkui/cli add toast

Setup

Put one Toaster in the root layout. It draws every toast, so it is there once for the whole app. Then call toast.add from anywhere: a click handler, a form action, code outside React.

import { Toaster } from "@/components/ui/toast"

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Toaster />
      </body>
    </html>
  )
}

import { toast } from "@/components/ui/toast"

toast.add({
  title: "Event created",
  description: "Sunday, December 3 at 9:00 AM",
})

Status

type adds an icon before the text: success, info, warning or error, each in its own colour. The toast itself stays neutral. Write the title so it says what happened without the icon.

An action

actionProps adds one button, most often Undo. toast.add returns the toast's id, so the button can close it. A toast with a button stays ten seconds instead of five, so there is time to reach it. Keep it to one action; a choice between two belongs in a dialog.

Following a piece of work

toast.promise takes a promise and shows one toast for it: a spinner while it runs, then the success or the error in the same place. A toast that is loading does not leave by itself; it stays until the work ends or someone closes it.

Staying until closed

A toast leaves after five seconds, or ten when it has a button. timeout sets another time for one toast, and 0 keeps it until someone closes it. Use that for a message a person has to act on; anything they must not miss belongs on the page or in a dialog.

One toast, not five

Give a toast an id and adding it again updates the one on screen and restarts its timer, so five quick clicks on Copy show one toast.

Several at once

New toasts stack in front of older ones, which peek out behind. Moving the pointer onto the stack, or focusing it, opens it into a list. At most three show: when a fourth arrives the oldest hides, and comes back when there is room. Every timer waits while the pointer or focus is on the toasts.

Place

Toasts sit at the bottom, at the end of the screen: the right in a left-to-right page, the left in a right-to-left one. position on Toaster moves them. On a phone they take the full width at the bottom or the top.

API

Toaster draws the toasts; toast creates them. The parts (Toast, ToastContent, ToastTitle, ToastDescription, ToastAction, ToastClose, ToastViewport) are exported for a list you build yourself.

Accessibility

A toast is read aloud when it appears and never takes focus, so it does not interrupt what someone is doing.

• It is announced politely, after the screen reader finishes its sentence. priority: "high" interrupts; keep it for errors that need attention now.
• F6 moves focus to the toasts from anywhere on the page, and Tab then walks through them and their buttons. Escape closes the toast that has focus.
• The timer waits while the pointer or keyboard focus is on a toast, and while the window is in the background.
• Every toast has a close button named "Close", and the toasts sit in a region named "Notifications"; closeLabel and label translate them. On a touch screen a swipe toward the edge closes a toast too.
• The status icon is decoration. The title has to say what happened: "Could not send the invite", not "Error".
• A toast with a button stays ten seconds, since five is short to read it and reach the button with a keyboard or a screen magnifier. Even so, never put the only copy of something important in a toast, and give an action another way to be reached (Undo also in a menu, the error also beside the field).
• Do not use a toast for a form's validation errors: they belong beside the fields.