Registry / web-framework / react-hot-toast

react-hot-toast

library2.6.0jsnpmunverified

react-hot-toast is a highly regarded, lightweight, and customizable React notification library designed to display "smoking hot" toast messages with minimal setup and a beautiful default aesthetic. Currently stable at version 2.6.0, the package maintains an active and responsive release cadence, frequently introducing new features and performance enhancements. Notable recent updates include support for multiple toasters in v2.6.0, enhanced React Server Components (RSC) compatibility for Next.js 13 App Router in v2.4.1, and significant bundle optimizations in v2.3.0. Its key differentiators include a powerful Promise API that automatically handles loading, success, and error states, an exceptionally small bundle size of less than 5kb, and versatile headless hooks (`useToaster`) for developers requiring complete control over the UI. The library is built with accessibility in mind and ships with TypeScript types, promoting robust and type-safe development practices. It provides a simple `Toaster` component and a `toast` function that can be called anywhere in your application.

web-framework

npm install react-hot-toast

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REACT-HOT-TOAST

react-hot-toast

web-frameworkjavascriptv2.6.0

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.

toast

✓ import toast from 'react-hot-toast';

✗ 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

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

✗ 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

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

✗ const { useToaster } = require('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.

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;

Debug

Known issues

breakingThe 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`.

affects: >=2.3.0-beta.1

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

affects: >=2.4.1

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

affects: <2.5.1

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

affects: >=2.6.0

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

affects: >=2.3.0

Errors

Common errors & fixes

ReferenceError: require is not defined

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.

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()

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.

Upgrade

Version history

2.6.0latest on npm

Audit

Dependencies

reactrequiredPeer dependency required for React component rendering.

react-domrequiredPeer dependency required for DOM rendering of React components.

csstyperequiredRuntime dependency added in v2.5.1 to avoid warnings related to CSS type definitions.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/timolins/react-hot-toast ↗

packagehttps://www.npmjs.com/package/react-hot-toast ↗

homepagehttps://react-hot-toast.com ↗