React Hot Toast Notifications

Common errors

• ReferenceError: require is not defined

  cause Attempting to use CommonJS `require` syntax in an environment (e.g., modern Next.js, ES Modules in Node.js) that primarily expects or enforces ES Modules after the v2.3.0-beta.1 update.
  fix Refactor your imports to use ES Module syntax (e.g., `import toast from 'react-hot-toast';`) and ensure your build tools are configured for ESM.

• Maximum update depth exceeded. This can happen when a component repeatedly calls setState inside componentWillUpdate or componentDidUpdate.

  cause This error, particularly during unit testing, was a known issue in versions prior to v2.4.0 due to an infinite loop in component rendering logic.
  fix Upgrade `react-hot-toast` to version `2.4.0` or higher, which includes a fix for this infinite loop during testing.

• TypeError: Cannot read properties of undefined (reading 'message') when using toast.promise()

  cause In versions prior to v2.5.1, the `toast.promise()` API made success/error messages optional, but some internal handling might not have gracefully managed promises resolving or rejecting without specific message properties, or incorrect promise usage.
  fix Ensure your promise resolution/rejection consistently provides an object with a `message` property for clear toast display, especially for older versions. Upgrade to `v2.5.1` or newer, which improved `toast.promise()` to make messages truly optional and allow async functions.

Warnings

• breaking The package moved to a new ESM compliant build setup using `.mjs` extensions and `tsup` for bundling. This could break existing CommonJS setups or older bundler configurations without proper resolution settings.
  Fix: Ensure your project's bundler (e.g., Webpack, Rollup, Next.js) is configured to correctly handle ES Modules (`.mjs` files) and check your `package.json` resolutions if issues arise. Prefer ESM `import` statements over CommonJS `require`.
• gotcha Improved React Server Components (RSC) support for Next.js 13 App Router requires the 'use client' directive for components interacting with `react-hot-toast` to ensure they render in the client environment as expected.
  Fix: Add `'use client'` at the top of any component file where `react-hot-toast` components or hooks are used, particularly within a Next.js App Router context.
• gotcha Prior to v2.5.1, `csstype` was not explicitly listed as a direct dependency, which could lead to warnings about missing peer dependencies in some environments or require manual installation.
  Fix: Upgrade to `react-hot-toast@2.5.1` or newer to automatically include `csstype` as a dependency and resolve potential warnings.
• gotcha Version 2.6.0 introduces support for multiple toasters, along with new `dismissAll` and `removeAll` APIs. While adding functionality, existing custom multi-toaster implementations might benefit from refactoring to use the new ergonomic API, potentially affecting previous logic for managing multiple toast containers.
  Fix: Review your application's multi-toaster logic. If you were manually managing multiple `Toaster` instances, consider adopting the `id` prop on `Toaster` and the new `dismissAll(id?)` and `removeAll(id?)` functions for better control and integration.
• gotcha Version 2.3.0 significantly improved bundle setup and exposed a new `react-hot-toast/headless` entry point. Users consuming headless features from older versions might need to update their import paths or adapt to the new structure.
  Fix: For headless use cases, explicitly import from `react-hot-toast/headless` if you were previously relying on other internal paths or if you experience build issues related to headless functionality.

Install

• npm install react-hot-toast npm
• yarn add react-hot-toast yarn
• pnpm add react-hot-toast pnpm

Imports

• toast
  wrong:

  import { toast } from 'react-hot-toast';

  correct:

  import toast from 'react-hot-toast';

  The primary `toast` function is a default export. Using a named import for it is incorrect. Since v2.3.0-beta.1, the package is ESM compliant, impacting CommonJS `require` usage.
• Toaster
  wrong:

  import Toaster from 'react-hot-toast';

  correct:

  import { Toaster } from 'react-hot-toast';

  The `Toaster` component is a named export. Attempting a default import will fail. CommonJS `require` patterns (`const { Toaster } = require('react-hot-toast');`) are supported but ESM is preferred since v2.3.0-beta.1.
• useToaster
  wrong:

  const { useToaster } = require('react-hot-toast');

  correct:

  import { useToaster } from 'react-hot-toast';

  The `useToaster` hook is a named export, primarily used for headless implementations. Modern JavaScript projects should use ES Modules; direct CommonJS `require` might necessitate specific bundler configurations after v2.3.0-beta.1 changes for ESM compliance.

Quickstart

This example demonstrates how to integrate `react-hot-toast` by adding the `Toaster` component once to your application and then triggering notifications using the `toast` function from any part of your code. It shows a basic button click initiating a simple toast.

import toast, { Toaster } from 'react-hot-toast';
import React from 'react';

const notify = () => toast('Here is your toast.');

const App = () => {
  return (
    <div>
      <button onClick={notify}>Make me a toast</button>
      <Toaster />
    </div>
  );
};

export default App;