Sonner

Sonner

From Emil Kowalski's ask-sonner skill (emilkowalski/skills), checked against the Sonner docs (sonner.emilkowal.ski) and the source at 2.0.8 (emilkowalski/sonner src/; 2.0.8 went to npm on 2026-08-09, 2.0.7 on 2025-08-02). The skill has ten errors against the source, most of them shared with the docs, corrected below where each fact sits; every correction names the source file. Sonner is two pieces: one <Toaster /> that renders and a plain toast() function that queues, joined by a module-level store, so most failures are a missing or doubled Toaster, a toaster that filters the toast out, or styles that lose the cascade. Toast motion in general is ui-animation; the owner's app gives feedback in place and uses no toast library (app-ui).

Apply only the routes and checks for the selected job. Read a linked skill's named file from its installed folder when available, or from the linked source. Report an unavailable required reference instead of inventing it. [skill-authoring, DISTRIBUTION.md#composing-skills]

The rules

1. Mount exactly one <Toaster />, near the root, unconditionally [Emil Kowalski, ask-sonner]. A second mounted Toaster duplicates every toast; a conditional or per-page one loses them.
2. Call toast() only from client code. It is a plain function with no hook or provider, and it does nothing on the server: a server action returns its result and the client calls toast() [Emil Kowalski, ask-sonner].
3. Target toasters by id deliberately. An untargeted toast renders only in Toasters without an id; a Toaster with an id shows only toasts sent to it (index.tsx).
4. Update a toast by passing its id again instead of dismissing and re-creating it; a stable id also stops StrictMode's double effect from duplicating it [Emil Kowalski, ask-sonner].
5. Climb the styling ladder only as far as the change needs, and go headless with toast.custom() once more than a few classes need !important [Emil Kowalski, ask-sonner].
6. Set theme explicitly. It defaults to 'light' and does not follow the OS; pass "system" or the app's resolved theme [Emil Kowalski, ask-sonner].
7. Read active toasts with toast.getToasts() outside React and useSonner() inside it; toast.getActiveToasts() does not exist (state.ts).
8. Never count on the Toaster beating a modal <dialog>: it is a z-index, not the top layer (Stacking and modal dialogs).

Setup

[Emil Kowalski, ask-sonner] Install with pnpm i sonner; the peer dependency is React 18 or 19.

1. One <Toaster />, mounted once, as close to the root as possible. In Next.js it goes in layout.tsx; it works inside server components because index.tsx starts with 'use client'.
2. toast() from client code: event handlers, effects, callbacks.

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

Picking the call

[Emil Kowalski, ask-sonner]

• toast.custom receives the id, jsx: (id: number | string) => React.ReactElement (state.ts). The docs say it "receives the Toast as an argument, giving you access to all properties"; the source passes only the id, which is what the skill said.
• The action button still closes a non-dismissible toast; the cancel button does nothing when dismissible: false (if (!dismissible) return;, index.tsx).
• No close button renders on toast.custom toasts or on loading toasts, even with closeButton (index.tsx).

Recipes

• Update a toast [Emil Kowalski, ask-sonner]: call toast() again with the same id; only the props you pass change, and toast.success(…, { id }) changes the type. This is a loading-to-success flow without toast.promise:

  const id = toast.loading('Uploading…');
  toast.success('Uploaded', { id });
  

• Persist with { duration: Infinity }; dismiss one with toast.dismiss(id) or all with toast.dismiss() [Emil Kowalski, ask-sonner]. duration is read as toast.duration || toasterDuration || 4000, so duration: 0 falls back to the default instead of closing at once (index.tsx).

• Read active toasts with useSonner() in React (it returns { toasts }) and toast.getToasts() outside it; toast.getHistory() returns every toast, kept to MAX_HISTORY_SIZE = 100 in 2.0.8 by dropping dismissed toasts above it, never one still on screen. The skill and the docs (/other) say toast.getActiveToasts(): that is a method on the internal ToastState, which is not exported; state.ts ends with Object.assign(basicToast, {…}, { getHistory, getToasts }) (state.ts, the same in v2.0.7).

• Links or components in the text [Emil Kowalski, ask-sonner]: pass a function for the title or description, toast(() => <a href="…">View</a>).

• Several toasters: give one <Toaster id="canvas" /> and send to it with toast('…', { toasterId: 'canvas' }). The filter is if (id) return toasts.filter((toast) => toast.toasterId === id); return toasts.filter((toast) => !toast.toasterId);, so an untargeted toast renders in every Toaster that has no id, and if every Toaster has an id it renders nowhere (index.tsx, the same in v2.0.7). The skill said "Without toasterId, every toaster renders the toast", which holds only when no Toaster has an id.

• Close callbacks: onAutoClose fires on timeout. onDismiss fires on the close button, a swipe and toast.dismiss(id) (or toast.dismiss() for all) (the toast.delete effect runs deleteToast(); toast.onDismiss?.(toast);). Action and cancel clicks call deleteToast() and fire neither (index.tsx). The skill and docs said onDismiss "fires on close button or swipe". There is no single "closed" callback [Emil Kowalski, ask-sonner].

• toast.promise beyond the basics (state.ts):

  • It also takes description (which can be a function of the result) and finally.
  • It returns the toast id with an unwrap() that resolves or rejects like the original promise; with no loading option it returns only { unwrap }.
  • The first argument is a promise or a function returning one.
  • A resolved Response with !ok becomes the error toast (HTTP error! status: N); a resolved Error instance also becomes the error toast; a resolved React element replaces the toast as a default toast.
  • With no success option the loading toast is dismissed; with no loading option no toast shows until the promise settles.

Styling: the escalation ladder

[Emil Kowalski, ask-sonner] Climb only as far as the change requires; jumping to the top rung early is fine (it is the recommended end state), lingering in the middle is not.

1. Defaults, plus richColors on the Toaster for colorful success and error, and invert to flip against the theme.
2. Inline tweaks: toastOptions={{ style: {…} }} on the Toaster for all toasts, or style per toast() call.
3. Classes on parts: toastOptions={{ classNames: { toast, title, description, … } }} (all keys in API.md). Sonner's styles win the cascade, so every class needs !important (Tailwind !text-red-900). If you are marking more than a few things important, go headless.
4. Headless: toast.custom() with your own JSX, wrapped in your own toast() abstraction. The docs call it "the recommended approach as people usually either use the defaults or go fully custom". unstyled: true is the halfway house.

• One rule per type: classNames.success, .error and the other type keys go on the toast's <li>, and default is the key for plain toast() toasts (index.tsx).
• Theme colors are CSS custom properties on [data-sonner-toaster][data-sonner-theme='light'] (--normal-bg: #fff; --success-bg: hsl(143, 85%, 96%); --success-text: hsl(140, 100%, 27%); …) in styles.css. Overriding them is another rung, but neither the skill nor the docs name it: treat it as source-observed, not a documented API.
• Icons [Emil Kowalski, ask-sonner]: per type through the Toaster's icons (which also takes close), per toast through icon, and null removes one.
• Theme [Emil Kowalski, ask-sonner]: theme defaults to 'light' and does not track the OS. theme="system" follows prefers-color-scheme live through a matchMedia change listener (index.tsx). With next-themes, the docs put <Toaster theme={resolvedTheme as ToasterProps['theme']} /> in a 'use client' wrapper (docs: Toaster). app-ui reads its saved theme with useSyncExternalStore(subscribe, readStored, () => "system") (app-ui TOKENS.md); that resolved value is what theme would take.

Behavior read from the source

All from index.tsx and styles.css at 2.0.8; none of it is in the skill.

Screen readers and the hotkey

• The container is <section aria-live="polite" aria-relevant="additions text" aria-atomic="false" tabIndex={-1}>, and each toast an <li tabIndex={0}>.
• Its label is ${containerAriaLabel} ${hotkeyLabel} ("Notifications alt+T"); customAriaLabel replaces the whole label. Both are Toaster props.
• hotkey is a string[], default ['altKey', 'KeyT']: every entry must match, each a modifier property name or an event.code. It expands the stack and focuses it, Escape collapses it, and hotkey={[]} turns it off (hotkey.length > 0 && ...). Focus returns to the previously focused element on blur or unmount.
• testId renders data-testid on the toast <li>, which matches the e2e runner's default testIdAttribute (tester-army-e2e RUNNER-SETUP.md); that skill's query order puts getByRole first and getByTestId last (tester-army-e2e WRITING-TESTS.md).

Swipe

• Dismiss at SWIPE_THRESHOLD = 45 px or a velocity above 0.11 px/ms, in an allowed direction only. Directions come from position; override them with swipeDirections [Emil Kowalski, ask-sonner].
• Movement the other way is damped by 1 / (1.5 + |delta| / 20), and the direction locks after 1px.
• Right-click, buttons, loading toasts and non-dismissible toasts don't swipe; selecting text cancels the swipe.

Sizes and timing

• TOAST_WIDTH = 356, GAP = 14, VISIBLE_TOASTS_AMOUNT = 3, TOAST_LIFETIME = 4000, TIME_BEFORE_UNMOUNT = 200 ("Equal to exit animation duration").
• Toasts transition transform 400ms, opacity 400ms, height 400ms, box-shadow 200ms; a non-front toast removed while collapsed uses transition: transform 500ms, opacity 200ms.
• The timer pauses while the stack is expanded (hover), while the user interacts (pointer down) and while the tab is hidden (expanded || interacting || isDocumentHidden).
• Under @media (prefers-reduced-motion) the stylesheet sets transition: none !important; animation: none !important; on [data-sonner-toast], its children and .sonner-loading-bar.
• offset defaults to '24px' (VIEWPORT_OFFSET) and mobileOffset to '16px' (MOBILE_VIEWPORT_OFFSET); the mobile value applies under @media (max-width: 600px), so at 600px and below. The skill and the docs (/toaster) say 32px and "< 600px" (the same in v2.0.7).

Right-to-left

dir defaults to getDocumentDirection(), which reads <html dir>, falls back to the computed direction, and returns 'ltr' only on the server; the type is 'rtl' | 'ltr' | 'auto', and 'auto' re-reads the document. A right-to-left app needs no prop. The skill and docs give the default as 'ltr'.

Toasts created before the Toaster

In 2.0.7 and earlier, a toast created before the Toaster subscribes is lost. From 2.0.8 subscribe replays active toasts: "A toast can be created before the Toaster had a chance to subscribe, e.g. when it's called in an effect of a component rendered above the Toaster. Replay whatever is still active so it doesn't get lost." (state.ts).

Stacking and modal dialogs

• The toaster is z-index: 999999999, not the top layer, so a native <dialog> opened with showModal() paints over it whatever its z-index. Moving the Toaster to the document root fixes an ancestor's stacking context, not a top-layer dialog. This follows from MDN's top layer rules, not from Sonner's docs.
• In 2.0.8 the section carries data-react-aria-top-layer, which v2.0.7 lacks. That it keeps toasts usable over React Aria modals is a reading of the attribute's name; React Aria's docs were not checked.
• The other view: anti-slop-ui puts "Layers that must float (menus, popovers, toasts, dialogs)" in the top layer, through "the popover attribute and <dialog> with showModal()" (anti-slop-ui DETAILS.md, with the techniques in modern-css POPOVER-AND-DIALOG.md). Sonner does not do that. Both hold: a toast library on a z-index works until a modal dialog opens, and then the dialog wins.

Where other skills differ

• Toast timing. ui-animation's ui-animation TIMING.md gives "| toast | 250-350 in, 150-200 out | emphasized in, exit out | 0% |". Sonner enters with a 400ms transform; a removed front toast keeps its 400ms transform and opacity transitions but unmounts at 200ms (TIME_BEFORE_UNMOUNT, "Equal to exit animation duration"), and a collapsed non-front toast fades its opacity over 200ms. Neither wins; use the table for your own toasts and leave Sonner's own timing alone unless you go headless.
• Reduced motion. ui-animation's rule 8: "Reduce, don't remove: with reduced motion, movement becomes short fades; feedback and state changes stay" (ui-animation SKILL.md). Sonner's stylesheet removes every transition and animation instead. Both are in use; a headless toast can follow ui-animation's rule.
• A visible countdown. ui-animation ui-animation PATTERNS.md: "A self-dismissing notification shows its time left: an animated border visibly counts down how long it stays." Sonner pauses its timer on hover, pointer interaction and a hidden tab, so a countdown drawn on a Sonner toast must pause with it.
• app-ui (the owner's design) has no toast component and no Sonner: it confirms in place (app-ui OVERLAYS.md), puts errors with a retry action inside the results card (app-ui DATA-VIEWS.md), and reads "Saved" on the save toggle (app-ui CONTROLS.md). Its motion tokens still name a toast: "| --duration-medium | 350ms | panels and toasts closing |" (app-ui TOKENS.md). Sonner's stylesheet doesn't read those tokens, so a styled Sonner still unmounts at 200ms, not 350ms.

Troubleshooting

[Emil Kowalski, ask-sonner], with the rows the source corrects marked.

Prove it

Exactly one Toaster is mounted (count [data-sonner-toaster] in the DOM, per toaster id); a toast fired from a client handler appears once under StrictMode; an updated toast keeps its id and changes type; toast.getToasts() returns the visible toasts; a targeted toast shows only in its Toaster and an untargeted one only in the id-less one; dark mode follows the app's theme; styles survive a production build and a view transition; a screen reader announces a new toast and Alt+T focuses the stack; and a toast opened while a showModal() dialog is up is checked for whether the dialog covers it.