react-hot-toast: A 5 KB Toast Library for React, and Where It Stops

The problem react-hot-toast solves, and for whom

React applications need a way to tell the user that something happened outside the current view: a save succeeded, a request failed, a background job finished. Wiring that by hand means a context provider, a portal, a queue, dismissal timers, and animation state. react-hot-toast packages all of that into two exports. You mount one Toaster component, and then call toast() from anywhere, including code that has no access to component props or context.

The audience is React developers who want notifications to work on first render without choosing a CSS framework. The README describes the library as "Lightweight, customizable and beautiful by default," and the package.json enforces that claim through size-limit entries: dist/index.js and dist/index.mjs are each capped at 5.5 KB, and the headless builds at 2.5 KB. Those are build-time budgets, not measured bundle sizes for your app, but they tell you the maintainer treats size as a constraint rather than a marketing line.

It is not aimed at teams that need a general notification system with severity levels, persistence, or a notification center. It is aimed at the transient message: appears, waits, disappears.

How the Toaster and toast() fit together

The architecture is deliberately thin. The package exports a default toast function and a named Toaster component. The Toaster is the renderer: it is the thing that owns the visual stack and the animation lifecycle. The toast function is the emitter: it is imported directly, not obtained from a hook or a provider, so a module that never touches React components can still fire a notification.

That split is why the README's example works with so little ceremony. There is no provider wrapping the tree, no reducer, no store subscription in application code. The Toaster registers itself when it mounts, and toast() dispatches into whatever store the package keeps internally.

The package also exposes a headless entry point. The package.json exports map defines a "./headless" subpath with its own types, import, and require targets, and the README lists "Headless Hooks" as a feature, pointing at useToaster(). That subpath is the escape hatch: if the default rendering does not match your design, you take the state layer and render the toasts yourself. The headless build carries a tighter 2.5 KB limit, which is consistent with it dropping the default renderer.

The promise API is the other mechanism worth naming. The README describes it as an "Automatic loader from a promise," meaning you hand the library a promise and it manages the pending, success, and error states of the same toast. That is a real reduction in code for the common fetch-then-notify pattern, and it is the feature most likely to justify the dependency.

Installing react-hot-toast and firing a first toast

The README gives two install paths. With pnpm:

pnpm add react-hot-toast

With npm:

npm install react-hot-toast

Either command adds the package to your dependencies. The package.json declares "engines": { "node": ">=10" }, so the install itself has no modern-Node requirement, though your React version and build tooling will.

The README's getting-started example is the smallest working setup. You import the default export and the named Toaster, call toast() in a handler, and mount Toaster once in the tree:

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

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

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

After this renders, clicking the button should produce a toast in the corner of the viewport. If nothing appears, the first thing to check is whether Toaster is actually mounted; toast() has no renderer to talk to without it.

The README points to https://react-hot-toast.com/docs for the full API reference. That page is where the options for positioning, duration, and custom rendering live, and the README does not reproduce them.

Where the library runs out of road

The README documents no confirmation dialog, no warning severity, and no way to render a toast outside the React tree. Those are not bugs; they are scope decisions. But they shape what you can build. A destructive-action confirmation is a modal problem, not a toast problem, and reaching for toast() to solve it will produce something that disappears before the user can decide.

The FAQ-style searches around this project include "react hot toast confirm" and "react hot toast warning." Neither has an obvious answer in the README, and the README does not claim either capability. If your design calls for a warning color or a blocking confirm, verify against the docs site before assuming the library covers it.

The other boundary is rendering context. Because toast() is a module-level function, it does not know about your theme provider, your i18n instance, or your router unless you pass that information in when you call it. A toast fired from a Redux thunk or a fetch interceptor renders with whatever the Toaster has, not with the context of the component that triggered the request. That is the trade for being callable from anywhere, and it is the one people hit after the demo works.

react-hot-toast against React-Toastify and sonner

React-Toastify is the comparison people search for most often, and the difference is structural rather than cosmetic. React-Toastify ships a styled component and a CSS import; you mount a ToastContainer and pull in its stylesheet. react-hot-toast ships its styles with the component, which is why the size-limit caps exist and why the README can call it "beautiful by default." If you want to control the markup entirely, react-hot-toast's headless subpath gives you the state without the renderer, and React-Toastify's approach gives you a styled system you override.

sonner is the other name that comes up. It is a separate toast library for React with its own API surface. Its internals are not described here, so the honest comparison is limited to positioning: react-hot-toast's pitch is a small default build plus a headless escape hatch, and the size-limit configuration in package.json is the concrete evidence for the first half of that pitch.

If your requirement is a notification center with read state and history, none of these three is the right shape. That is an application-level concern, and a toast library will fight you.

Maintenance, licence, and the cost of upgrading

The repository is not archived, and the last push was on 2026-09-16, the same day v2.6.1 was released. The release history shows v2.6.0 on 2025-08-15 and v2.5.2 on 2025-02-15, so the cadence between 2.5.2 and 2.6.0 was roughly six months, and 2.6.1 followed 2.6.0 after about thirteen months. That is a slow, low-churn release pattern rather than a fast-moving one, which is normal for a library whose surface is two exports.

Upgrade cost is low by construction. The package has no runtime dependencies listed in package.json, only devDependencies for Jest, size-limit, and testing-library. There is no peer dependency on a CSS framework. The main upgrade risk is the size-limit gate: if a release raises the 5.5 KB cap for dist/index.js, that is a deliberate decision by the maintainer, and you should notice it before it lands in your bundle.

The licence is MIT, declared in package.json and present as a LICENSE file at the repository root. MIT permits commercial use and modification with attribution and no warranty. That is a statement about the licence text, not legal advice; if your organisation has a policy on third-party licences, run it through that process.

Editorial conclusion

Adopt react-hot-toast if you want toast notifications in a React app without pulling in a styling system or a state container, and if the promise API covers your async flows. Do not adopt it if you need confirm dialogs, warning-level semantics, or a toast rendered outside React's tree; the README documents none of those. Before committing, check the size-limit entries in package.json against your own bundle budget and confirm the headless entry point exists in the version you install.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. timolins/react-hot-toast on GitHub