react-hot-toast

Smoking hot React Notifications. Lightweight, customizable and beautiful by default.

weekly downloads2.8M

versionv2.6.0

licenseMIT

categoryfrontend

reactnotificationstoastsnackbar

Overview

react-hot-toast is a notification library for React applications that weighs less than 5kb gzipped including styles. It provides a simple API for displaying toast notifications with pre-built attractive styling, while remaining fully customizable through theming, CSS classes, or custom React components. The library ships with zero configuration required—you render a component once and call toast() functions anywhere in your app.

The package gained traction in the React ecosystem for solving a common problem: most toast libraries were either too heavy for performance-sensitive apps or required extensive configuration to look decent. react-hot-toast inverts this by providing beautiful defaults while exposing escape hatches for customization. It handles common patterns like loading states, promise-based workflows, and positioning without requiring developers to manage state manually.

With 2.7 million weekly downloads, it's used across React and Next.js applications ranging from dashboards to e-commerce platforms. The library is particularly popular in projects where bundle size matters—Next.js apps, mobile-first PWAs, and serverless environments. Its MIT license and TypeScript support make it suitable for both open-source and commercial projects.

The architecture centers on a global toast manager that maintains notification state outside React's component tree, allowing toast() calls from event handlers, utility functions, or even non-React code. The library provides both imperative (toast.success()) and promise-based APIs (toast.promise()), plus a headless useToaster() hook for developers needing full control over rendering.

Quick Start

typescript

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

function App() {
  const [email, setEmail] = useState('');

  const handleSubscribe = async () => {
    const subscribePromise = fetch('/api/subscribe', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email })
    }).then(res => {
      if (!res.ok) throw new Error('Subscription failed');
      return res.json();
    });

    toast.promise(subscribePromise, {
      loading: 'Subscribing...',
      success: (data) => `Welcome! Check ${data.email} for confirmation`,
      error: (err) => `Error: ${err.message}`
    });
  };

  const showCustomToast = () => {
    toast.custom((t) => (
      <div style={{
        background: t.visible ? '#333' : 'transparent',
        padding: '16px',
        borderRadius: '8px',
        color: 'white',
        transition: 'all 0.3s'
      }}>
        <strong>Custom notification</strong>
        <button onClick={() => toast.dismiss(t.id)}>Dismiss</button>
      </div>
    ), { duration: 4000 });
  };

  return (
    <div>
      <Toaster 
        position="top-center"
        toastOptions={{
          duration: 3000,
          style: {
            background: '#363636',
            color: '#fff'
          },
          success: {
            iconTheme: { primary: '#10b981', secondary: 'white' }
          }
        }}
      />
      
      <input 
        type="email" 
        value={email} 
        onChange={(e) => setEmail(e.target.value)}
        placeholder="Enter email"
      />
      <button onClick={handleSubscribe}>Subscribe</button>
      <button onClick={() => toast.success('Simple success!')}>Basic Toast</button>
      <button onClick={showCustomToast}>Custom Toast</button>
    </div>
  );
}

export default App;

Use Cases

Form submission feedback: Display loading toasts during API calls, automatically updating to success or error states using toast.promise(). Handles the entire lifecycle of async operations without manual state management.

Real-time notifications: Show incoming messages, updates, or alerts in collaborative apps like project management tools or chat applications. The low bundle size makes it suitable for apps already loading significant real-time infrastructure.

Onboarding flows: Guide users through multi-step processes with contextual toasts that appear at specific actions. Custom duration and positioning allow notifications to complement tutorials without blocking UI elements.

Error boundary fallbacks: Integrate with React error boundaries to display user-friendly error toasts when components crash, providing actionable feedback instead of blank screens or default error UIs.

Background task completion: Notify users when long-running operations complete (file uploads, report generation, batch processing) while they navigate to other parts of the application. Persistent toasts ensure messages aren't missed during navigation.

Pros & Cons

Pros

+Extremely lightweight at <5kb gzipped with styles included, minimal impact on bundle size and load times
+Zero configuration needed for attractive notifications—works beautifully out of the box with sensible defaults
+Promise API automatically handles loading/success/error states without manual toast lifecycle management
+Headless useToaster() hook allows complete custom rendering while maintaining toast state logic
+Positioning system supports six locations without additional CSS or wrapper components
+Full TypeScript support with proper type inference for custom toast options and renderers

Cons

−Limited built-in animations compared to heavier libraries—only basic fade and slide transitions included
−No native swipe-to-dismiss gestures on mobile devices, requiring custom implementation for touch interactions
−Global singleton pattern can complicate testing scenarios that need isolated toast state per test case
−Documentation for advanced customization (custom renderers, animation timing) is sparse beyond basic examples
−No built-in queue management options for limiting simultaneous toasts or priority ordering

Alternatives

notistackv3.0.2

Highly customizable notification snackbars (toasts) that can be stacked on top of each other

frontendnotistackenqueueSnackbar

1.2M / week

react-toastifyv11.0.5

React notification made easy

frontendreactnotification

3.0M / week

sonnerv2.0.7

An opinionated toast component for React.

frontendreactnotifications

9.9M / week

Comparisons

sonner vs react-hot-toast

frontend

react-hot-toast vs react-toastify

frontend

Install

bash

npm install react-hot-toast

bash

pnpm add react-hot-toast

bash

bun add react-hot-toast

Overview

Quick Start

typescript

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

function App() {
  const [email, setEmail] = useState('');

  const handleSubscribe = async () => {
    const subscribePromise = fetch('/api/subscribe', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email })
    }).then(res => {
      if (!res.ok) throw new Error('Subscription failed');
      return res.json();
    });

    toast.promise(subscribePromise, {
      loading: 'Subscribing...',
      success: (data) => `Welcome! Check ${data.email} for confirmation`,
      error: (err) => `Error: ${err.message}`
    });
  };

  const showCustomToast = () => {
    toast.custom((t) => (
      <div style={{
        background: t.visible ? '#333' : 'transparent',
        padding: '16px',
        borderRadius: '8px',
        color: 'white',
        transition: 'all 0.3s'
      }}>
        <strong>Custom notification</strong>
        <button onClick={() => toast.dismiss(t.id)}>Dismiss</button>
      </div>
    ), { duration: 4000 });
  };

  return (
    <div>
      <Toaster 
        position="top-center"
        toastOptions={{
          duration: 3000,
          style: {
            background: '#363636',
            color: '#fff'
          },
          success: {
            iconTheme: { primary: '#10b981', secondary: 'white' }
          }
        }}
      />
      
      <input 
        type="email" 
        value={email} 
        onChange={(e) => setEmail(e.target.value)}
        placeholder="Enter email"
      />
      <button onClick={handleSubscribe}>Subscribe</button>
      <button onClick={() => toast.success('Simple success!')}>Basic Toast</button>
      <button onClick={showCustomToast}>Custom Toast</button>
    </div>
  );
}

export default App;

Use Cases

Pros & Cons

Pros

+Extremely lightweight at <5kb gzipped with styles included, minimal impact on bundle size and load times
+Zero configuration needed for attractive notifications—works beautifully out of the box with sensible defaults
+Promise API automatically handles loading/success/error states without manual toast lifecycle management
+Headless useToaster() hook allows complete custom rendering while maintaining toast state logic
+Positioning system supports six locations without additional CSS or wrapper components
+Full TypeScript support with proper type inference for custom toast options and renderers

Cons

−Limited built-in animations compared to heavier libraries—only basic fade and slide transitions included
−No native swipe-to-dismiss gestures on mobile devices, requiring custom implementation for touch interactions
−Global singleton pattern can complicate testing scenarios that need isolated toast state per test case
−Documentation for advanced customization (custom renderers, animation timing) is sparse beyond basic examples
−No built-in queue management options for limiting simultaneous toasts or priority ordering