Toast

A toast reports the result of an action in a small panel above the page, so users stay in their task. It appears at the bottom of the screen, in the right corner on a wide viewport, and closes by itself after five seconds. Users close it earlier with the close button, with a swipe down or to the right, or with the Escape key while focus is inside it. Several toasts form a stack, which expands and pauses the timeouts while the pointer rests on it or keyboard focus is inside it. Toaster is rendered once around the app, and the components inside it add toasts with useToastManager.

UsageCopy Anchor Link

"use client";

import { Button } from "@biem/ui/components/ui/button";
import { Toaster, useToastManager } from "@biem/ui/components/ui/toast";

function TransferButton() {
	const toastManager = useToastManager();

	function sendTransfer() {
		toastManager.add({
			title: "Transfer sent",
			description: "The warehouse ships 12 cases on Monday.",
		});
	}

	return <Button variant="outline" onClick={sendTransfer}>Send transfer</Button>;
}

export function ToastDefault() {
	return (
		<Toaster>
			<TransferButton/>
		</Toaster>
	);
}

ExamplesCopy Anchor Link

InfoCopy Anchor Link

Not every message reports a success or a problem, and some simply keep users up to date on work that continues elsewhere. With type set to "info", the toast marks its message as neutral information, so users take note of it without feeling asked to act.

SuccessCopy Anchor Link

After a completed action, users want to know that it went through before they move on. Setting type to "success" marks the toast as that confirmation, and users recognize the positive outcome at a glance.

WarningCopy Anchor Link

Between success and failure lie results that need attention soon without stopping the task. A toast with type set to "warning" flags such a result, so users notice it early and decide when to deal with it.

ErrorCopy Anchor Link

When an action fails, users need to know at once that their step had no effect. Through type set to "error", the toast reports the failure as such, leaving the description to say what went wrong and what users can try next.

LoadingCopy Anchor Link

Work that users start does not always finish at once, and its end is often unknown in advance. Set to "loading", type keeps the toast open without a timeout and shows that the work is still running, so users keep track of it while they continue their task. Once the work ends, code updates the toast with the outcome or closes it.

With ActionCopy Anchor Link

Many results invite a direct response, such as reversing a step that users took too quickly. Through actionProps the toast offers that response as an action of its own, so users act where the message appears instead of searching the page for the matching control.

Disabled ActionCopy Anchor Link

An action is sometimes unavailable for a moment, for example until the step before it has finished. As long as actionProps contain disabled, the toast keeps the action in view, so users know it exists, but neither a click nor the keyboard triggers it.

PromiseCopy Anchor Link

Requests to a server take a moment and end either in success or in failure. Passed to promise, the request gets a single toast that reports the work while it runs and turns into a confirmation or an error once the request settles, so users learn the outcome in the place where they saw it begin.

Custom TimeoutCopy Anchor Link

Five seconds suffice for a short confirmation, but a message with details that users want to note needs more time. Given a timeout of its own in milliseconds, such a toast stays open for exactly that time, while every other toast keeps the timeout of the Toaster.

Without TimeoutCopy Anchor Link

A message that asks users to do something later must not vanish before they have read it. With timeout set to 0, the toast stays open until users close it themselves.

DeduplicatedCopy Anchor Link

Repeated actions can stack the same message several times when users trigger them in quick succession. Under a fixed id, the toast that is still open updates in place and restarts its timeout, so users see one message that stays current.

Update from CodeCopy Anchor Link

Over the course of a process, its message changes from work in progress to a result. Through update, code gives the open toast with a given id new content and a new type, so users follow the process in one place instead of in a new toast for every step. As soon as the type is no longer "loading", the toast closes by itself after its timeout.

Close from CodeCopy Anchor Link

A message about running work stays open until that work ends, and sometimes the work stops before it finishes. Called with the id of the toast, close takes the message away at once, so users never rely on a status that no longer applies. Without an id, close ends every open toast.

LimitCopy Anchor Link

Several actions in quick succession can fill the screen with messages and cover the content users work with. Here, limit set to 1 keeps only the newest toast in view, while older ones stay open with their timeouts running and return as newer toasts close.

Custom ToastCopy Anchor Link

Some results need more than a title and a description, such as values that users compare with what they expected. Composed from ToastProvider and the parts of the toast instead of Toaster, a list of its own decides what every toast contains. Values that belong to a single toast travel in data, so each message holds exactly what users need to judge the result.

Swipe DirectionCopy Anchor Link

Where a vertical gesture already has a meaning, such as scrolling on a touch screen, a swipe down should not dismiss a message by accident. Set to "right", swipeDirection lets users close the toast only with a swipe to the right, and a swipe in any other direction leaves it open.

Disabled CloseCopy Anchor Link

Like any control, the close button can be unavailable for a moment. Marked as disabled, it stays in view but no longer closes the toast, while the timeout, a swipe and the Escape key still do.

API ReferenceCopy Anchor Link

ToasterCopy Anchor Link

useToastManagerCopy Anchor Link

useToastManager returns the toasts of the nearest Toaster or ToastProvider and the functions that manage them. toasts is the array of open toasts, newest first, which a custom list passes to Toast one by one. add shows a toast with the options below and returns its id. update takes an id and the options to replace, or a function that receives the current toast and returns them, and it accepts every option except id. close closes the toast with the given id, or all toasts when it is called without one. promise takes a promise and the options for loading, success and error: it shows a toast of the type "loading", turns it into "success" or "error" when the promise settles, and returns a promise that settles in the same way. Each of the three is a string, which becomes the description, or an object with the options that update accepts, and success and error also accept a function that receives the result or the error and returns one of the two. It is a hook, so it renders no element and has no props of its own. Outside Toaster and ToastProvider, it throws an error.

toastCopy Anchor Link

toast is the manager whose toasts a Toaster shows when it receives no toastManager. It has the functions add, update, close and promise that useToastManager returns, but not toasts, and it works outside a component, for example in a function that handles a failed request. Every Toaster without a toastManager shows its toasts, so an app that adds toasts with toast renders exactly one such Toaster. It is an object, so it renders no element and has no props of its own.

createToastManagerCopy Anchor Link

createToastManager returns a new manager with the functions add, update, close and promise. Pass it to toastManager of a Toaster or a ToastProvider, which then shows the toasts that code adds through the manager. It is a function, so it renders no element and has no props of its own, and it takes no arguments.

ToastProviderCopy Anchor Link

ToastPortalCopy Anchor Link

ToastViewportCopy Anchor Link

ToastCopy Anchor Link

ToastContentCopy Anchor Link

ToastTitleCopy Anchor Link

ToastDescriptionCopy Anchor Link

ToastActionCopy Anchor Link

ToastCloseCopy Anchor Link