Working With Sonner

Working With Sonner guides setup, rendering, styling, and troubleshooting for the Sonner React toast library. It starts with a single Toaster mounted near the application root and toast calls made from client code. In Next.js, the root layout can host the Toaster, including inside server components; a server action returns its result so receiving client code can show the toast.

The integration uses these imports:

import { Toaster } from 'sonner'; // once, in layout
import { toast } from 'sonner';   // anywhere client-side

The guide maps notification requirements to plain messages, success or error variants, loading indicators, promise-bound status, action and cancel buttons, custom JSX in the standard shell, or fully headless rendering. Promise success and error handlers can receive the resolved value or error. An action normally closes its toast unless its click handler prevents the default behavior.

Use it when wiring up Sonner, choosing the appropriate call, updating notifications, integrating a design-system toast, or investigating missing, duplicated, clipped, or incorrectly styled messages. It directs exact prop-name, type, and default questions to the companion API reference.

Avoid per-page or conditional Toaster placement, which can unmount notifications or create duplicates. Intentional multiple toasters need distinct identifiers and explicit toasterId targeting; otherwise every toaster renders the message. The skill's examples are illustrative and should be checked against the installed library version and application conventions.

Inputs are the notification's purpose, its lifecycle, desired styling, and any observed rendering problem. The guidance supplies setup and call patterns, lifecycle recipes, a styling escalation path, and symptom-specific checks.

Updating a toast reuses its id so only supplied properties change; switching to a success call can change its type. Persistence uses an infinite duration, and dismissal can target one id or all active messages. React code can read active toasts with useSonner, while non-React code uses toast.getActiveToasts. Title or description functions can render links or components. Dismissal and timeout have separate onDismiss and onAutoClose callbacks rather than a single combined close event.

Styling progresses from defaults and richColors through inline styles and classes on individual parts to headless toast.custom rendering. The guide warns that injected styles win the cascade, making extensive important overrides a signal to use headless rendering. Headless mode retains positioning, stacking, and swipe behavior and can be wrapped in an application-level toast abstraction. Icons can be replaced globally by type, overridden per toast, or removed with null.

Troubleshooting checks include duplicate root mounts and development StrictMode effect calls, missing injected CSS after view transitions, Shadow DOM style placement, and ancestor stacking contexts. Stable toast ids can prevent duplicate effect notifications, while event-handler calls avoid the development double-invoke path. Explicit stylesheet import addresses lost styles; Shadow DOM requires placing the relevant style tag inside its root.

A toast hidden behind an overlay may require moving the Toaster outside dialog or portal containers near the document root. Loading that never finishes can indicate an unsettled promise; notifications that never close also warrant checking duration and dismissibility. Swipe direction follows position unless overridden. Edge spacing uses separate desktop offset and mobileOffset controls, with the guide describing defaults of 32px and 16px and a mobile breakpoint below 600px.

The skill covers Sonner in React and Next.js, with next-themes supplying a resolved theme where used. Theme defaults to light rather than tracking the operating system automatically; choose system mode or pass the application's resolved theme. CSS or Tailwind customization, Astro and view-transition stylesheet issues, and Shadow DOM placement appear in its troubleshooting coverage. Final visible states, accessibility, and reduced-motion behavior remain part of shipping checks.