React Hot Toast: Lightweight Toast Notifications Guide

Practical, code-focused guide to using react-hot-toast for building performant React toast notifications — installation, promise toasts, hooks, customization and integration.

What is react-hot-toast? (Short answer)

react-hot-toast is a tiny, dependency-free React notification library that provides non-blocking toast messages with a minimal API. It focuses on speed, accessibility, and an elegant API for quick adoption in both small apps and large projects.

The library is designed around simple hooks and a single Toaster provider placed near your app root. You call functions like toast.success(), toast.error(), or the promise-aware toast.promise() to show contextual notifications.

Because it’s lightweight and customizable, react-hot-toast fits well when you need reliable toast messages with a small bundle impact and fast developer experience.

Why choose react-hot-toast for React toast notifications?

react-hot-toast focuses on three things: low weight, a straightforward API, and polished UX out of the box. Compared with heavier notification systems, it gives instant productivity with sensible defaults and optional customization when you need it.

It has built-in features for different notification types (success, error, loading), timer control, and promise-based flows. This makes it trivial to show stateful notifications around async actions without manual state management.

Additionally, react-hot-toast is accessible by default: toasts are announced to assistive technologies and you can configure positions and styling to respect your app’s design system.

Installation & Setup

Start by installing the package. Use npm or yarn depending on your project:

npm install react-hot-toast
# or
yarn add react-hot-toast

Then add the <Toaster /> component at the top level of your app (usually in src/App.jsx or src/index.jsx). It renders the toast container and holds global options.

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

function App() {
  return (
    <>
      <Toaster position="top-right" />
      <YourAppRoutes />
    
  );
}

export default App;

That’s it. After adding Toaster, you can import the global toast utility anywhere in your component tree and call it directly.

Basic usage and examples

Use the central API to show simple messages. The toast function supports types: success, error, loading, and plain messages.

import toast from 'react-hot-toast';

toast('Hello world');                 // default
toast.success('Saved!');              // success
toast.error('Request failed');        // error
const id = toast.loading('Saving...'); // loading (returns id)

Because toast.loading returns an id, you can update the same toast later:

toast.success('Saved!', { id }); // replaces loading toast with success

Use this pattern when you want to avoid stacking multiple toasts for the same action — common in form submissions and uploads.

Promise toasts: show status for async actions

The toast.promise() helper is one of react-hot-toast’s most convenient features. It accepts a promise and an object of messages for pending, success, and error states.

toast.promise(
  fetchData(), 
  {
    loading: 'Fetching data…',
    success: 'Data loaded',
    error: 'Failed to load',
  }
);

This automatically shows a loading toast, then updates it with success or error depending on the promise resolution, so you don’t need manual open/close logic. It’s concise and ideal around network requests, uploads, and long-running tasks.

Under the hood, it uses the promise lifecycle to replace the pending toast with the final result, improving UX and avoiding toast spam during retries or repeated requests.

Customization & theming

You can customize position, duration, styles, and the toast component itself. The <Toaster /> accepts global options, while individual toasts accept overriding options.

<Toaster
  position="bottom-center"
  toastOptions={{
    duration: 4000,
    style: { background: '#111827', color: '#fff' }
  }}
/>

If you need fully custom visuals, pass a render function to toast() and return any JSX. This is useful when you want icons, actions, or progress bars inside a toast.

toast(({ id }) => (
  <div>
    <strong>Upload in progress</strong>
    <button onClick={() => toast.dismiss(id)}>Cancel</button>
  </div>
));

Remember to keep toasts concise — long content can be distracting. Use toasts for transient status messages and actions like „Undo” or „Retry”.

Hooks and API patterns

react-hot-toast is hook-friendly because the API is global — you import toast where you need it. For component-local behavior, tie toast calls to event handlers or effects.

Example pattern: show a toast in an async handler inside a component. This keeps side effects localized and avoids prop drilling:

async function onSubmit(data) {
  const promise = api.save(data);
  await toast.promise(promise, { loading: 'Saving…', success: 'Saved', error: 'Cannot save' });
}

For advanced control, keep the returned toast id and call toast.dismiss(id) or toast.update(id, { ... }). This supports timeouts, retries, and conditional updates.

Accessibility, performance & best practices

Accessibility: react-hot-toast uses ARIA-live regions to announce notifications to screen readers. Keep messages short and focused so they’re helpful when announced.

Performance: the library is tiny and doesn’t require heavy setup. Avoid heavyweight custom JSX inside toasts that trigger extra renders; prefer lean components and memoization for complex renderers.

Best practices: limit toast duration for critical messages, deduplicate repeated notifications by reusing ids, and use promise toasts for async flows so users understand progress and outcome without manual state tracking.

Integrations & helpful links

For full docs and advanced options, consult the official react-hot-toast docs. The docs include customization examples, TypeScript hints, and animations.

If you want a hands-on tutorial, this dev.to tutorial walks through building a toast system and shows common patterns for real apps.

For source and issues, see the project on GitHub. Link using keyword-rich anchors, for example: react-hot-toast docs and react-hot-toast GitHub.

Common pitfalls & troubleshooting

If toasts don’t appear, confirm <Toaster /> is mounted once (usually at app root). Duplicate Toaster instances can cause unexpected behavior.

If ARIA announcements are not firing, ensure your app’s focus management and modals aren’t blocking live regions. Also check CSS overrides that might hide visually rendered toasts.

When customizing, guard against heavy JSX inside toasts that can bloat re-renders. Use lightweight render functions and offload heavy logic outside the rendering path.

FAQ

Selected from common developer questions and „People also ask” patterns.