ask-sonner

Working With Sonner

SDD gate. If this fired on a new, non-trivial feature or behaviour change and there is no approved spec + plan under 02-DOCS/wiki/sdd/, hand off to ../specify/SKILL.md first — it runs brainstorm → spec → plan → tasks before any code, then routes back here once the plan is approved. Build straight from here only for a genuinely one-line / low-risk change, or a bug fix restoring intended behaviour. Method: ../sdd/SKILL.md.

Hand-offs. Choosing between libraries at all is ../pick-ui-library/SKILL.md's (its answer for toasts is this one). Customising the toast's motion beyond the props here is ../animate/SKILL.md's. App wiring is ../react/SKILL.md's and ../nextjs/SKILL.md's.

A guide skill for Sonner, the toast library. When a task involves Sonner — wiring it up, rendering toasts, styling them, or fixing them — answer from this file first. Full prop tables for <Toaster /> and toast() live in references/api.md; read it when you need an exact prop name, type, or default.

Setup

Two pieces, and only two:

1. One <Toaster />, mounted once, as close to the root as possible (in Next.js: layout.tsx — it works inside server components). Never render it per-page or conditionally; a second mounted Toaster duplicates every toast.
2. toast() called from client code — event handlers, effects, callbacks. It's a plain function, no hook or provider needed, but it does nothing on the server: in a server action, return the result and call toast() in the client code that receives it.

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

Picking the right call

You want	Call
Plain message	toast('Title') — add { description } for a second line
Success / error / info / warning icon	toast.success('…'), toast.error('…'), etc.
Spinner while you manage state yourself	toast.loading('…'), then update it by id
Loading → success/error tied to a promise	toast.promise(promise, { loading, success, error }) — success/error accept functions receiving the resolved value/error
Button that does something	{ action: { label, onClick } } — closes the toast unless onClick calls event.preventDefault(); cancel is the secondary variant
Custom JSX, default toast shell	toast(<jsx />)
Custom JSX, no styles at all	toast.custom((t) => <jsx />) — headless, t gives you the id to dismiss