Guide · Open source
How to use react-hot-toast: install, show toasts and promise loaders
Updated · written with AI from the project's own documentation and checked against our catalogue data
react-hot-toast is an open-source React library for showing short pop-up messages, called toasts, that tell users something happened, such as a save succeeding or an error occurring. This guide covers installing it, rendering the Toaster component, triggering toasts from anywhere in your app, and using the promise helper for loading states. By the end you will have a working notification in a React project.
react-hot-toasttimolins/react-hot-toast · ★ 11k · MIT Install options & downloads Quick start
- 1Check prerequisites. Confirm you have a React project and Node.js with npm or pnpm available.
- 2Install the package. Run pnpm add react-hot-toast or npm install react-hot-toast in your project folder.
- 3Import toast and Toaster. Import the default toast function and the Toaster component from react-hot-toast.
- 4Render the Toaster once. Place the Toaster component somewhere in your app so it can display every emitted notification.
- 5Call toast() where needed. Trigger toast('your message') from event handlers or after async work to show a notification.
What you need before you install react-hot-toast
You need a React project and Node.js with either npm or pnpm. The library is built specifically for React, so it is not suitable for projects that use other frameworks.
- A React project
- Node.js
- npm or pnpm
Install react-hot-toast with pnpm or npm
Run the install command for your package manager from your project folder. The README lists both options.
- With pnpm: install the package using the pnpm add command
- With npm: install the package using the npm install command
pnpm add react-hot-toast
npm install react-hot-toastAdd the Toaster component to your app
Add the Toaster component once to your app. It renders all notifications that are emitted, so you only need it in one place. Import both the default toast function and the Toaster component from the package.
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>
);
};Show a toast from anywhere in your code
Once the Toaster is rendered, you can call the toast function from any part of your app. The example above calls it from a button click handler, but the same call works anywhere the function can run, such as after a request finishes.
- Call toast() with a string to show a plain message
- Call toast() inside event handlers or after async work completes
Show a loading toast with the promise helper
The README describes a Promise API that shows an automatic loader while a promise is pending. This suits async actions such as saving data or sending a request. The README excerpt provided here does not include the exact call signature, so check the official documentation at https://react-hot-toast.com/docs for the full usage.
- The loader is shown automatically while the promise is pending
- Useful for teams wanting a promise-based loading toast for async actions
Build your own notification UI with headless hooks
If you want full control over how notifications look, the library offers headless hooks, including useToaster(). This lets you create your own notification UI on top of the toast state. Refer to the documentation for the hook's API details.
What people use it for
- Confirming that a form save or update succeeded
- Showing an error message when a request fails
- Displaying a loading toast while an async action is pending using the promise helper
- Building a custom notification look with the headless hooks
Frequently asked questions
How do I install react-hot-toast?
Run pnpm add react-hot-toast if you use pnpm, or npm install react-hot-toast if you use npm. Both commands come from the project README. You need a React project with Node.js installed.
Is react-hot-toast free to use?
The project is licensed under the MIT licence, as listed in the repository. Check the LICENSE file in the repository for the full terms before using it in a commercial product.
Does react-hot-toast work without React?
No. The library is built specifically for React, so projects that do not use React are not a good fit.
Why is my toast not showing?
The README says to add the Toaster component to your app first, since it renders all emitted notifications. If you call toast() without a rendered Toaster, nothing will appear. Make sure the Toaster is mounted in your component tree.
What are the alternatives to react-hot-toast?
Comparable projects include react-toastify, notistack, sonner and react-toast-notifications. Pick based on whether you want a small headless-friendly library, a full styled set of options, or a specific look.
Is react-hot-toast good for persistent notification centers?
Not really. The README focuses on transient toasts, which are short messages that appear and go away. If you need a persistent notification center, look at a different tool.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
react-hot-toast suits React developers who want simple, lightweight toast messages, a promise-based loader, or headless hooks to build their own UI. It is a poor fit for non-React projects, persistent notification centers, or teams that need a complete design system.
Install options & downloads