Next.js Toast Notifications with Drivn

Drivn installs through a small CLI that writes the component source straight into your repository — there is no runtime package to version-lock beyond Sonner itself. From the root of your Next.js 16 project run npx drivn add toast. The Toast wrapper depends on the sonner and lucide-react packages, so the CLI notes them; if they are not already installed, add them once and you are set. The command writes a single toast.tsx under your UI directory — the CLI reference documents every flag, including targeting a custom path or adding several components at once. After install you own the file, so a future Drivn release will not overwrite your edits, and the whole wrapper — the icon map and the token-based style object — is a few lines you can read top to bottom. Commit the change for a clean baseline before wiring it in.

A toast container should mount exactly once, high enough in the tree to sit above every route. In the App Router that place is the root layout. The Toaster is a client component — its source opens with 'use client' because Sonner manages a portal and a queue — but you render it directly inside a Server Component layout, because a Server Component may render a client child. Import Toaster into app/layout.tsx and drop it just before the closing </body>, after {children}. That single mount serves every page; you never render a second Toaster. Because it draws nothing until a toast fires, its position in the layout affects only stacking order, not layout flow. See the installation guide for the surrounding project setup.

With the Toaster mounted, any client component can import toast and call it from an event handler. toast('Changes saved') shows a neutral message; toast.success, toast.error, toast.info, and toast.warning each render with the matching pre-wired lucide icon — a green check, a red cross, an info circle, a warning triangle. Pass a second argument for a description or an action button, exactly as the Sonner API describes, because Drivn re-exports toast unchanged. The one rule the App Router adds: the call must originate on the client, so the component that calls toast needs a 'use client' directive. A Server Component cannot call toast directly — it has no browser to render into — which is why toasts fire from handlers, effects, or callbacks. Drop a Button beside it for a save-with-feedback flow, and see the Toast examples for more variants.

The common Next.js flow is a form that posts to a Server Action, then confirms the result. Because a Server Action runs on the server, it cannot fire a toast itself — but the client component that invokes it can. Wrap the action in a client form handler: await the action, then branch on its return to call toast.success or toast.error. For a pending state while the action is in flight, toast.loading returns an id you pass to toast.success(msg, { id }) to swap the spinner for the result in place — the spinning Loader2 icon Drivn pre-wires is exactly what shows during that loading phase. This keeps the mutation on the server and the feedback on the client, which is the boundary the App Router is built around. The Toast reference lists every method the re-exported toast supports.

Everything the container renders is set in one place — the Toaster wrapper you own. Change where toasts appear by passing a position prop such as top-center or bottom-left; the default is Sonner's bottom-right. The icon map and the theming are already wired in the source: five lucide-react icons keyed by variant, and a style object that maps Sonner's CSS variables onto Drivn's design tokens — --normal-bg to var(--card), the text to var(--card-foreground), the border to var(--border), and a --border-radius of 12px. Because those read your Tailwind theme tokens, the toast surface re-themes for dark and light mode automatically when you recolor them in theming. To swap an icon or the radius, edit the object in place — there is no config file and no variant map to thread through. The block below is copied verbatim from toast.ts.