Sonner (Toasts)

Toaster is the Sonner-backed toast host. You mount it once near the root of the app, then fire transient messages from anywhere with the toast function from sonner. Toasts are non-blocking: they stack in a corner, carry a semantic icon, and dismiss themselves. Reach for them to confirm an action, surface a recoverable error, or report background work without interrupting the user. For the system-level framing of the same component, see Notifications.

Live demo

The interactive story below runs from the deployed Storybook.

Usage

Source: sonner.tsx

import { Toaster } from "@beacon/design-system";
import { toast } from "sonner";

// Mount the host once, near the app root.
<Toaster />

// Then fire toasts from anywhere.
toast("Event has been created");
toast.success("Profile updated successfully");
toast.error("Something went wrong");
toast.warning("Your session is about to expire");

// Track a promise; the toast transitions through each state.
toast.promise(saveRecord(), {
  loading: "Loading...",
  success: "Done!",
  error: "Error",
});

Parts

Part	Role
Toaster	The toast host. Mount once; it renders the stack, wires theme via next-themes, and supplies the semantic icons.
toast (from sonner)	The imperative trigger. Call it to enqueue a toast.

toast variants

Call	Icon	Use for
toast(message)	none	A neutral, informational message.
toast.success(message)	check circle	A completed, successful action.
toast.error(message)	octagon X	A failed or rejected action.
toast.warning(message)	triangle alert	A caution the user should notice.
toast.info(message)	info	Informational context, no action required.
toast.promise(p, opts)	spinner then result	Background work with loading, success, and error states.

Toaster accepts all props of the underlying Sonner Toaster (for example position and richColors).

When to use

• Confirm a save, create, or delete that the user just triggered.
• Report a recoverable error without blocking the workflow.
• Surface the result of background work via toast.promise.

Do not use a toast for a decision the user must act on before continuing. For a blocking confirmation use a dialog instead.