{"id":12056,"library":"sonner","title":"Sonner: Opinionated Toast Component for React","description":"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.","status":"active","version":"2.0.7","language":"javascript","source_language":"en","source_url":"https://github.com/emilkowalski/sonner","tags":["javascript","react","notifications","toast","snackbar","message","typescript"],"install":[{"cmd":"npm install sonner","lang":"bash","label":"npm"},{"cmd":"yarn add sonner","lang":"bash","label":"yarn"},{"cmd":"pnpm add sonner","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for React applications.","package":"react","optional":false},{"reason":"Peer dependency for rendering React components.","package":"react-dom","optional":false}],"imports":[{"note":"The Toaster component is a named export. Requires a modern bundler for ESM. CommonJS environments might struggle or require transpilation.","wrong":"const { Toaster } = require('sonner');","symbol":"Toaster","correct":"import { Toaster } from 'sonner';"},{"note":"The main utility function for creating toasts is a named export. Ensure your bundler handles ESM correctly.","wrong":"const toast = require('sonner').toast;","symbol":"toast","correct":"import { toast } from 'sonner';"},{"note":"When using TypeScript, always import types using `import type` to avoid bundling them into your JavaScript output.","wrong":"import { ToastOptions } from 'sonner';","symbol":"ToastOptions","correct":"import type { ToastOptions } from 'sonner';"}],"quickstart":{"code":"import { Toaster, toast } from 'sonner';\nimport './index.css'; // Or wherever your Sonner CSS is located\n\nfunction App() {\n  return (\n    <div>\n      <Toaster richColors position=\"bottom-right\" />\n      <h1>Welcome to my App</h1>\n      <button onClick={() => toast('My first toast!')}>\n        Show Simple Toast\n      </button>\n      <button onClick={() => toast.success('Operation successful!')}>\n        Show Success Toast\n      </button>\n      <button onClick={() => toast.loading('Loading data...', { \n        id: 'loading-toast' \n      })}>\n        Show Loading Toast\n      </button>\n      <button onClick={() => {\n        toast.dismiss('loading-toast');\n        toast.error('Operation failed!');\n      }}>\n        Dismiss Loading & Show Error\n      </button>\n    </div>\n  );\n}\n\nexport default App;\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<2.0.5"},{"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\" />`.","message":"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.","severity":"gotcha","affected_versions":"<2.0.7"},{"fix":"Upgrade Sonner to v2.0.4 or a newer version to ensure the `onDismiss` callback fires correctly upon toast dismissal.","message":"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.","severity":"gotcha","affected_versions":"<2.0.4"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<2.0.2"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The CSS file for Sonner is not being correctly imported or found by the bundler.","error":"Module not found: Can't resolve 'sonner/dist/style.css'"},{"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.","cause":"The `toast` utility function was not correctly imported or is being called on an undefined variable.","error":"TypeError: toast is not a function"},{"fix":"Confirm you are importing it as a named export: `import { Toaster } from 'sonner';`. Ensure you have `<Toaster />` present in your component tree.","cause":"The `<Toaster />` component was not correctly imported or recognized.","error":"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."},{"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.","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.","error":"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')"}],"ecosystem":"npm"}