sonner

library2.0.7jsnpmunverified

Sonner is an opinionated toast component for React, designed to be beautiful by default and simple to use. It emphasizes accessibility and provides a modern look and feel, inspired by macOS notifications. The library is currently stable at version 2.0.7 and receives regular updates, often with multiple patch releases between minor or major versions. Its key differentiators include built-in support for various toast types (success, error, info, warning, loading), rich customization options through props, and a strong focus on developer experience with a simple `toast()` API. Unlike some alternatives, Sonner aims to provide a consistent, aesthetically pleasing experience without requiring extensive styling, while still offering flexibility for specific needs. It also excels at handling asynchronous operations with its promise-based toast updates.

web-framework

npm install sonner

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SONNER

sonner

web-frameworkjavascriptv2.0.7

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Toaster

✓ import { Toaster } from 'sonner';

✗ const { Toaster } = require('sonner');

The Toaster component is a named export. Requires a modern bundler for ESM. CommonJS environments might struggle or require transpilation.

toast

✓ import { toast } from 'sonner';

✗ const toast = require('sonner').toast;

The main utility function for creating toasts is a named export. Ensure your bundler handles ESM correctly.

ToastOptions

✓ import type { ToastOptions } from 'sonner';

✗ import { ToastOptions } from 'sonner';

When using TypeScript, always import types using `import type` to avoid bundling them into your JavaScript output.

This quickstart demonstrates how to set up the Toaster component, trigger various toast types (simple, success, loading, error), and programmatically dismiss a toast using its ID.

import { Toaster, toast } from 'sonner'; import './index.css'; // Or wherever your Sonner CSS is located function App() { return ( <div> <Toaster richColors position="bottom-right" /> <h1>Welcome to my App</h1> <button onClick={() => toast('My first toast!')}> Show Simple Toast </button> <button onClick={() => toast.success('Operation successful!')}> Show Success Toast </button> <button onClick={() => toast.loading('Loading data...', { id: 'loading-toast' })}> Show Loading Toast </button> <button onClick={() => { toast.dismiss('loading-toast'); toast.error('Operation failed!'); }}> Dismiss Loading & Show Error </button> </div> ); } export default App;

Debug

Known issues

breakingVersion 2.0.0 introduced breaking changes, primarily through the removal of deprecated props that were present in earlier major versions or beta releases. Users migrating from v1 or early v2 betas must review the official documentation for updated API usage.

fix

Consult the official Sonner documentation (sonner.emilkowal.ski) for specific migration paths and updated prop names. Update your code to use the new API surface.

affects: >=2.0.0

gotchaPrior to v2.0.5, users commonly encountered issues with the CSS import path, leading to unstyled toasts. This was a significant pain point for many users.

fix

Ensure you are on version 2.0.5 or newer. The correct way to import the styles is typically `import 'sonner/dist/style.css';` in your main entry file or component.

affects: <2.0.5

gotchaBefore v2.0.7, Sonner did not officially support multiple `<Toaster />` components within a single application, which could lead to unpredictable rendering or behavior issues if attempted.

fix

Upgrade to v2.0.7 or newer. If you need multiple distinct toast display areas, use the `toasterId` prop on each `<Toaster />` instance: `<Toaster toasterId="my-first-toaster" />`.

affects: <2.0.7

gotchaThe `onDismiss` callback on toasts might not have fired consistently or reliably in versions prior to v2.0.4, impacting logic dependent on toast dismissal.

fix

Upgrade Sonner to v2.0.4 or a newer version to ensure the `onDismiss` callback fires correctly upon toast dismissal.

affects: <2.0.4

gotchaIn versions prior to v2.0.2, calling `toast.dismiss()` without providing a specific toast `id` would not dismiss any toasts, even if there was only one active.

fix

Upgrade to v2.0.2 or newer. Always provide a toast ID when calling `toast.dismiss(id)` for targeted removals. For global dismissal (dismissing the last toast without an ID), upgrade is necessary.

affects: <2.0.2

Errors

Common errors & fixes

Module not found: Can't resolve 'sonner/dist/style.css'

The CSS file for Sonner is not being correctly imported or found by the bundler.

fix

Ensure you have `import 'sonner/dist/style.css';` in your root `App.js`/`App.tsx` or `index.js`/`index.tsx` file. Verify your bundler configuration supports CSS imports.

TypeError: toast is not a function

The `toast` utility function was not correctly imported or is being called on an undefined variable.

fix

Ensure you are using `import { toast } from 'sonner';` and that the import statement is at the top of your file. Check for typos in the function call.

Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: undefined. You likely forgot to export your component from the file it's defined in, or you might have mixed up default and named imports.

The `<Toaster />` component was not correctly imported or recognized.

fix

Confirm you are importing it as a named export: `import { Toaster } from 'sonner';`. Ensure you have `<Toaster />` present in your component tree.

Error: Hydration failed because the initial UI does not match what was rendered on the server. There was an error while hydrating this message from the server: TypeError: Cannot read properties of null (reading 'removeChild')

This can occur in SSR/SSG environments if Sonner tries to access DOM elements before they are available, or if the markup differs between server and client.

fix

Wrap the component rendering toasts in a `useEffect` hook with an empty dependency array to ensure it only runs on the client, or use a dynamic import with `ssr: false` if using Next.js or similar frameworks.

Upgrade

Version history

2.0.7latest on npm

Audit

Dependencies

reactrequiredPeer dependency for React applications.

react-domrequiredPeer dependency for rendering React components.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/emilkowalski/sonner ↗

packagehttps://www.npmjs.com/package/sonner ↗

homepagehttps://sonner.emilkowal.ski ↗