Toast

Confirm what just happened with a short notification from anywhere in the app, then get out of the way.

Installation

You can add the toast using our CLI or manually:

Dark mode ready - this component follows BoardUI semantic tokens automatically. Set up theme switching.

CLI

Manual

The CLI copies the component source (with its internal dependencies) into your project and installs any required npm packages.

npx boardui@latest add toast

Using a shared UI package or custom import aliases? Configure your installation paths before running the CLI. Copy-paste examples use the default imports.

Anatomy

Render one Toaster near the root of the app, then call toast() from anywhere: an event handler, a server action's result, a data hook. Each toast is a Notification card in a NotificationViewport, so it has the same status icons, countdown bar, actions, and motion, and the stack closes its gaps with the same spring.

Use toast.success, toast.error, and toast.info for the status colours. Pressing an action runs it and dismisses the toast.

Update a toast

toast() returns an id. Pass it to toast.update to turn a long task's toast into its result, and to toast.dismiss to remove it. A toast with an Infinity duration stays until it is updated or dismissed.

const id = toast.info("Exporting customers", {  description: "Preparing 1,284 rows.",  icon: RiDownload2Line,  duration: Infinity, // stays until updated or dismissed  dismissible: false,});
await exportCustomers();
toast.update(id, {  title: "Export ready",  description: "customers.csv is in your downloads.",  status: "success",  icon: undefined,  duration: 4000, // a new duration restarts the countdown  dismissible: true,});

Position

Anchor the stack to any corner or to the middle of the top or bottom edge with position. Start and end follow the reading direction.

<Toaster position="top-center" />
// "top-start" | "top-center" | "top-end"// "bottom-start" | "bottom-center" | "bottom-end" (the default)

Duration and limit

Toasts dismiss themselves after five seconds, with a countdown bar along the bottom edge. Set duration on the Toaster or on a single toast. limit caps how many show at once, and reusing an id replaces a toast that is still on screen.

<Toaster  limit={3}        // toasts on screen at once; the oldest leave first  duration={5000}  // default countdown in milliseconds/>
toast("Saved", { duration: 2000 });          // per toasttoast("Syncing…", { duration: Infinity });   // until dismissedtoast("Draft saved", { id: "draft" });       // the same id replaces ittoast.dismiss("draft");                      // dismiss onetoast.dismiss();                             // dismiss all

Right-to-left

Place the Toaster inside DirectionProvider. The stack takes the direction into its portal, so end corners move to the left, the close button and actions mirror, and the countdown bar runs from right to left.

import { DirectionProvider } from "@/components/foundations/direction/direction";
<DirectionProvider locale="ar">  <Toaster position="bottom-end" closeLabel="إغلاق الإشعار" /></DirectionProvider>

Accessibility

The stack is a labelled region and a polite live region, so screen readers announce each toast as it arrives, and error toasts as alerts. Every countdown pauses while the pointer or keyboard focus is inside the stack, so nobody loses a message while reading it or reaching for its action.

Keep toasts for confirmations that need no answer. Ask for a decision with an alert dialog instead.