Sonner

Stacked toast notification system with promise/loading states, built on the sonner library with Unified UI styling.

Basic

Stacked toast notification system with promise/loading states, built on the sonner library with Unified UI styling. Trigger toasts from anywhere using the toast() function.

import { toast } from "@work-rjkashyap/unified-ui";

toast("Event has been created");
toast.success("Profile updated!");
toast.error("Something went wrong");
toast.warning("This action is irreversible");
toast.info("New version available");

import { toast } from "@work-rjkashyap/unified-ui";toast("Event has been created");toast.success("Profile updated!");toast.error("Something went wrong");toast.warning("This action is irreversible");toast.info("New version available");

Installation

Install the component via the CLI in one command.

npx @work-rjkashyap/unified-ui add sonner

pnpm dlx @work-rjkashyap/unified-ui add sonner

npx @work-rjkashyap/unified-ui add sonner

bunx @work-rjkashyap/unified-ui add sonner

If you haven't initialized your project yet, run npx @work-rjkashyap/unified-ui init first. See the CLI docs for details.

Or install the full package

Use this approach if you prefer to install the entire design system as a dependency instead of copying individual components.

npm install @work-rjkashyap/unified-ui

pnpm add @work-rjkashyap/unified-ui

yarn add @work-rjkashyap/unified-ui

bun add @work-rjkashyap/unified-ui

Anatomy

import { SonnerToaster } from "@work-rjkashyap/unified-ui";

Setup

Place <SonnerToaster /> once in your root layout:

// app/layout.tsx
import { SonnerToaster } from "@work-rjkashyap/unified-ui";

export default function RootLayout({ children }) {
	return (
		<html>
			<body>
				{children}
				<SonnerToaster />
			</body>
		</html>
	);
}

Examples

Basic Toasts

toast("A simple notification");
toast.success("Changes saved successfully");
toast.error("Failed to save changes");
toast.warning("Storage almost full");
toast.info("Update available");

toast("A simple notification");toast.success("Changes saved successfully");toast.error("Failed to save changes");toast.warning("Storage almost full");toast.info("Update available");

With Description

toast.success("Profile updated", {
description: "Your changes have been saved and will be visible to others.",
});

toast.error("Upload failed", {
description: "The file exceeds the 10MB size limit. Please compress and try again.",
});

toast.success("Profile updated", {description: "Your changes have been saved and will be visible to others.",});toast.error("Upload failed", {description: "The file exceeds the 10MB size limit. Please compress and try again.",});

With Action

toast("File deleted", {
description: "report-q4.pdf was moved to trash.",
action: {
  label: "Undo",
  onClick: () => restoreFile(),
},
});

toast.error("Connection lost", {
description: "Unable to reach the server.",
action: {
label: "Retry",
onClick: () => reconnect(),
},
});

toast("File deleted", {description: "report-q4.pdf was moved to trash.",action: {  label: "Undo",  onClick: () => restoreFile(),},});toast.error("Connection lost", {description: "Unable to reach the server.",action: {label: "Retry",onClick: () => reconnect(),},});

Promise-Based

toast.promise(uploadFile(), {
loading: "Uploading file...",
success: "File uploaded successfully!",
error: "Upload failed. Please try again.",
});

toast.promise(sendEmail(), {
loading: "Sending email...",
success: "Email sent!",
error: "Failed to send email.",
});

toast.promise(uploadFile(), {loading: "Uploading file...",success: "File uploaded successfully!",error: "Upload failed. Please try again.",});toast.promise(sendEmail(), {loading: "Sending email...",success: "Email sent!",error: "Failed to send email.",});

Loading Toast

const id = toast.loading("Processing payment...");

// Later, when done:
toast.success("Payment complete!", { id });

// Or on error:
toast.error("Payment failed", { id });

const id = toast.loading("Processing payment...");// Later, when done:toast.success("Payment complete!", { id });// Or on error:toast.error("Payment failed", { id });

Custom Duration

// Quick toast
toast.info("This disappears quickly", { duration: 1500 });

// Long toast
toast.warning("This stays for 10 seconds", { duration: 10000 });

// Persistent (must be dismissed manually)
toast.info("This stays until dismissed", { duration: Infinity });

// Quick toasttoast.info("This disappears quickly", { duration: 1500 });// Long toasttoast.warning("This stays for 10 seconds", { duration: 10000 });// Persistent (must be dismissed manually)toast.info("This stays until dismissed", { duration: Infinity });

Custom JSX

toast.custom((id) => (
<div className="flex items-center gap-3 bg-background border border-border rounded-lg p-3 shadow-lg">
  <div className="flex size-9 items-center justify-center rounded-full bg-primary/10 text-primary">
    <Mail className="size-4" />
  </div>
  <div className="flex-1 min-w-0">
    <p className="font-medium text-sm">New message</p>
    <p className="text-xs text-muted-foreground truncate">
      Hey! Are you available for a quick call?
    </p>
  </div>
  <Button size="sm" variant="ghost" onClick={() => toast.dismiss(id)}>
    Dismiss
  </Button>
</div>
));

toast.custom((id) => (<div className="flex items-center gap-3 bg-background border border-border rounded-lg p-3 shadow-lg">  <div className="flex size-9 items-center justify-center rounded-full bg-primary/10 text-primary">    <Mail className="size-4" />  </div>  <div className="flex-1 min-w-0">    <p className="font-medium text-sm">New message</p>    <p className="text-xs text-muted-foreground truncate">      Hey! Are you available for a quick call?    </p>  </div>  <Button size="sm" variant="ghost" onClick={() => toast.dismiss(id)}>    Dismiss  </Button></div>));

Props (SonnerToaster)

Prop	Type	Default	Description
`position`	`"top-left" \| "top-center" \| ... \| "bottom-right"`	`"bottom-right"`	Toast stack position.
`richColors`	`boolean`	`true`	Use distinct colors per toast type.
`closeButton`	`boolean`	`true`	Show close button on each toast.
`duration`	`number`	`4000`	Auto-dismiss duration in ms.
`visibleToasts`	`number`	`3`	Max visible toasts at once.
`expand`	`boolean`	`true`	Expand toast stack on hover.
`theme`	`"light" \| "dark" \| "system"`	`"system"`	Theme override.
`offset`	`number \| string`	`16`	Offset from viewport edge.
`gap`	`number`	`14`	Gap between toasts.
`toastOptions`	`object`	—	Custom class names for toast elements.
`className`	`string`	—	Additional CSS classes on container.

toast() API

Method	Description
`toast(message)`	Default toast.
`toast.success()`	Success toast with green styling.
`toast.error()`	Error toast with red styling.
`toast.warning()`	Warning toast with amber styling.
`toast.info()`	Info toast with blue styling.
`toast.loading()`	Persistent loading toast with spinner.
`toast.promise()`	Promise-based with loading/success/error.
`toast.custom()`	Render custom JSX.
`toast.dismiss()`	Dismiss a toast by ID.

Toast Options

Option	Type	Description
`description`	`string`	Body text below the title.
`duration`	`number`	Override auto-dismiss duration.
`action`	`{ label: string, onClick: () => void }`	Action button config.
`cancel`	`{ label: string, onClick: () => void }`	Cancel button config.
`id`	`string \| number`	Custom toast ID for updates.
`icon`	`ReactNode`	Custom icon.
`onDismiss`	`() => void`	Callback when toast dismisses.

Accessibility

Toasts use role="status" and aria-live="polite" for screen reader announcements.
Keyboard dismissible via Escape or the close button.
Focus management handled by sonner internally.
Action and cancel buttons are fully keyboard accessible.

For critical, blocking messages that require user action, use AlertDialog or ConfirmDialog instead of toast notifications.

Design Tokens

Token	Usage
`--background`	Toast background
`--foreground`	Toast title text
`--muted-foreground`	Toast description text
`--border`	Toast border
`--primary`	Action button background
`--primary-foreground`	Action button text
`--secondary`	Cancel button background
`--success`	Success toast accent
`--danger`	Error toast accent
`--warning`	Warning toast accent
`--info`	Info toast accent
`--radius-lg`	Toast border radius
`--shadow-lg`	Toast shadow

On this page