Sonner

Sonner is an opinionated toast component for React created by Emil Kowalski, the designer behind notification systems at Vercel and Linear. It ships a single <Toaster /> component and an imperative toast() function that can be called from anywhere in a React tree — no context provider or prop drilling required — to trigger stacked, animated, swipeable toast notifications.

Under the hood a lightweight pub-sub store decouples toast state from the render tree, and the library includes first-class support for promise-based toasts (loading to success/error), rich colors, custom themes, and Next.js App Router client components, while remaining dependency-free at runtime.

What You Get

• A <Toaster /> component and imperative toast() API with success/error/info/warning/loading variants
• Built-in promise handling that maps loading, success, and error states to toast content automatically
• Swipeable, stackable toasts with configurable position, gap, duration, and expand-on-hover behavior
• Light/dark/system theme support and a richColors mode for semantic color-coded toasts
• Zero runtime dependencies and a single dependency-free CSS file shipped alongside the JS

Common Use Cases

• Confirming form submissions or API mutations with success/error toasts
• Showing progress for async operations via toast.promise() (e.g. file uploads, checkout flows)
• Surfacing background job status (e.g. ‘Deploy started’ to ‘Deploy succeeded’) without blocking the UI
• Replacing native browser alerts with a dismissible, accessible, theme-aware notification system

Under The Hood

Architecture Sonner is a single-package React component library centered on an observer/pub-sub pattern in src/state.ts (the Observer class) that decouples imperative toast() calls from the render tree — calling toast.success(…) publishes to a subscriber list that the mounted <Toaster /> (src/index.tsx) picks up via ToastState.subscribe inside a useEffect, batching updates with ReactDOM.flushSync and requestAnimationFrame to avoid render-thrash. The Toaster component tracks per-toast heights (HeightT[]) and an offset/gap layout system to stack toasts, groups toasts by position (top-right, bottom-center, etc.) into separate <ol> lists, and delegates each toast’s swipe/dismiss/hover/timer lifecycle to the inner Toast component, which manages its own mount/removal/animation state locally via refs and timers rather than through the global store.

Tech Stack Pure TypeScript/React library (peer deps react/react-dom ^18 || ^19) with zero runtime dependencies — styling is a single hand-authored CSS file (src/styles.css, ~17KB) shipped alongside the JS rather than CSS-in-JS. Built with bunchee (a bundler for library authors) producing dual ESM/CJS output with type declarations (dist/index.mjs, dist/index.js, dist/index.d.ts). The repo is a pnpm+Turborepo monorepo (pnpm-workspace.yaml, turbo.json) housing the library alongside a docs website package; testing uses Playwright for e2e browser tests rather than a unit-test runner.

Code Quality Test coverage is a single Playwright e2e spec (test/tests/basic.spec.ts, 340 lines) driving the built Toaster in a real browser (opening, dismissing, swiping toasts) — there are no unit tests for state.ts’s Observer class or types. Source is fully typed (types.ts defines roughly 200 lines of exported interfaces: ToastT, ToasterProps, ToastClassnames, etc.), naming is consistent and descriptive, and error handling in state.ts’s promise() method carefully branches on Response/Error/plain-value results, with a try/catch fallback for older Safari’s matchMedia API (addListener) in index.tsx. index.tsx is a large (889-line) single file mixing the Toast and Toaster components plus utility functions, which increases the surface a contributor needs to hold in their head.

API Design The public API is minimal and idiomatic — a single <Toaster /> mounted once plus an imperative toast() function (and toast.success/error/info/warning/loading/promise/custom/dismiss) callable from anywhere in the tree without hooks or context providers, which the README demonstrates in under 10 lines. Object.assign is used to attach the typed sub-methods onto the base toast function, preserving full TypeScript intellisense. The promise() API elegantly maps loading/success/error states to toast content, including HTTP Response detection. Minor DX friction: dedicated getting-started docs live outside the repo (hosted at sonner.emilkowal.ski), and the ‘use client’ directive at the top of index.tsx/assets.tsx signals Next.js App Router awareness without being called out in the README.