Sonner: Opinionated Toast Component for React

Common errors

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

  cause 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

  cause 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.

  cause 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')

  cause 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.

Warnings

• breaking Version 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.
• gotcha Prior 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.
• gotcha Before 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" />`.
• gotcha The `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.
• gotcha In 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.

Install

• npm install sonner npm
• yarn add sonner yarn
• pnpm add sonner pnpm

Imports

• Toaster
  wrong:

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

  correct:

  import { Toaster } from 'sonner';

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

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

  correct:

  import { toast } from 'sonner';

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

  import { ToastOptions } from 'sonner';

  correct:

  import type { ToastOptions } from 'sonner';

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

Quickstart

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;