Toast notification

Overview

A toast is the system saying “done” in the corner of the screen. It announces a result the user already knows the cause of — they pressed Save, the toast confirms it landed. Toasts inherit the same five tones, fills, and icons as the Banner, so a settlement warning reads identically whether it lives in the page shell or rises out of the bottom-right. Where Banner is part of the page, Toast lives on top of it: floating, time-limited, and replaceable.

Anatomy

A 380 px-wide tinted card with a leading icon, one or two lines of copy, an optional inline action, a dismiss button, and a 2 px progress line at the bottom that drains as the auto-dismiss timer ticks.

Tones

Five tones, same fills and icons as Banner. The priority on announce-to-screen-reader differs: success / caution / info are polite; warning / critical are assertive (they interrupt the screen reader to read the toast immediately).

Content variants

Three content shapes cover every confirmation in the product. A toast that needs more shape than this isn't a toast — promote it to a banner or a modal.

Positions

Six positions, anchored to the viewport. Pick one per surface and stick to it — moving the toast around between routes makes the user hunt for the confirmation each time. Default is top-right on desktop and bottom-center on mobile.

Duration

Three durations cover the cases. Hover pauses the timer; the progress bar pauses with it. A duration of 0 makes the toast sticky — it stays until the user dismisses it or activates the inline action.

Stack

Multiple toasts stack with an 8 px gap. Newer toasts arrive at the position-anchored edge — top-positioned stacks grow downward, bottom-positioned stacks grow upward — so the newest message is always closest to the screen edge the eye is already watching.

Behavior

• 01Auto-dismiss is the default. Toasts last 5 seconds unless overridden. Quick confirms (3 s) when the message is one word; long toasts (8 s) when the user needs to read; sticky (0 ms) only when the toast carries an action that must be taken.
• 02Hover pauses, leave resumes. The timer freezes on mouseenter and resumes on mouseleave with the remaining duration. Focus / blur do the same — keyboard users get the same grace.
• 03One inline action, never two. The action sits below the description as an underlined text button. Activating it dismisses the toast. If you find yourself wanting two actions, the message belongs in a banner or a modal — toast is for confirmation, not deliberation.
• 04Newest stacks toward the edge. For top-positioned stacks, new toasts append at the top and older ones drop down. For bottom-positioned stacks, new toasts append at the bottom and older ones rise. The newest message is always closest to the screen edge.
• 05Cap the queue at four. Past four visible toasts the stack stops being a queue and starts being a list. Discard the oldest as new ones arrive, or coalesce repeats (“3 orders saved”) so the user reads one message instead of three.
• 06Reduced motion drops the slide. Under prefers-reduced-motion: reduce the toast appears in place; the progress bar still drains so the user can still see how long they have. The auto-dismiss timer is independent of motion preference.

Accessibility

• Roles by tone: success, caution, and info use role="status" + aria-live="polite" so the screen reader finishes its current sentence before announcing the toast. Warning and critical use role="alert" + aria-live="assertive" — they interrupt because the user needs to know now.
• Keyboard: the toast is tabIndex=0 so the user can focus it and press Escape to dismiss. Tab moves focus into the toast, then onto the inline action and the dismiss button in DOM order.
• Focus does not leave the page.Toasts never steal focus on appear — that's the modal's job. Focus only lands on the toast if the user reaches for it.
• Don't carry meaning in colour alone. Every tone is paired with an icon (Check, WarningAmber, ErrorOutline, InfoOutlined) so colour-blind users still read the result. The title verb does the same job in words.
• Touch targets: the dismiss button is 28 × 28 px, below the 44 px touch-target floor — but the entire toast is also a focusable surface that Escape dismisses, so reaching for the small button is never the only path.

Code

Mount one Toaster at the app root and call toast() from anywhere — server actions, event handlers, optimistic mutations. The function returns the toast id so the caller can dismiss it imperatively (e.g. when an in-flight request resolves to an error).

import { Toaster, toast } from "@flatpay-dk/ui";

// Mount once at the app root — usually inside the providers.tsx tree.
<Toaster position="top-right" />

// Then anywhere in the tree:
toast.success("Order saved");
toast.warning("Settlement delayed", {
  description: "Your bank reported a temporary outage.",
});
toast.critical("Payment declined", {
  description: "Click to retry — the toast won't auto-dismiss.",
  duration: 0,
  action: { label: "Retry", onClick: retryPayment },
});

// Imperative dismiss — useful when the cause finishes resolving
const id = toast.info("Saving…", { duration: 0 });
await save();
toast.dismiss(id);

// Coalesce repeats by passing the same id
toast.info("3 orders saved", { id: "save-batch" });

// In a server action, fire from the client side after revalidation
const handle = async () => {
  const result = await saveOrder();
  if (result.ok) toast.success("Order saved");
  else toast.critical("Couldn't save", { description: result.error });
};

Best practices

Toast misuse is the loudest in the system — a wrong toast interrupts every user on every page. The questions below catch the common ones.

Props

toast()

<Toaster />

Related