react-hot-toast — Lightweight Toast Notifications for React

Introduction

react-hot-toast is a lightweight notification library for React that provides toast messages with smooth animations and a minimal API. It uses a hooks-based architecture, supports promise-aware toasts that track async operations, and ships at under 5 KB gzipped with no dependencies beyond React.

What react-hot-toast Does

• Displays success, error, loading, and custom toast notifications
• Tracks promises automatically with loading, success, and error states
• Provides smooth CSS-based enter and exit animations out of the box
• Supports custom JSX rendering for fully branded notification content
• Manages toast stacking, auto-dismiss timers, and pause-on-hover behavior

Architecture Overview

The library uses a headless notification store powered by React hooks. The Toaster component subscribes to the store and renders active toasts with CSS transitions. Each toast is an object with an ID, type, message, and configuration. The store handles queuing, deduplication, and automatic dismissal. Custom renderers receive the toast object and can return arbitrary JSX.

Self-Hosting & Configuration

• Install via npm and place a single Toaster component in your app root
• Configure position (top-left, top-center, top-right, bottom-left, etc.) on the Toaster
• Set default duration, style, and className via Toaster's toastOptions prop
• Use toast() imperatively from any component or callback without prop drilling
• Customize individual toasts by passing options to toast(), toast.success(), or toast.error()

Key Features

• Tiny bundle: under 5 KB gzipped with zero non-React dependencies
• Promise API: toast.promise() automatically shows loading, success, and error states
• Headless mode: use useToaster() hook for fully custom rendering without the default Toaster
• Accessible: includes ARIA live regions for screen reader announcements
• Emoji and icon support: built-in icons with customizable emoji or React component alternatives

Comparison with Similar Tools

• Sonner — similar lightweight approach with a more opinionated design and Framer Motion animations; slightly larger bundle
• React-Toastify — more feature-rich with progress bars and theme support; larger bundle at ~6 KB
• Notistack — Material UI integration with snackbar stacking; best for MUI-based projects
• Mantine Notifications — part of the Mantine ecosystem; tightly coupled to the Mantine component library

FAQ

Q: Can I use it with Next.js? A: Yes. Place the Toaster component in your root layout and call toast() from any client component or server action callback.

Q: How do I show a toast from outside a React component? A: The toast() function is a standalone import that works anywhere in your code, including utility functions and API interceptors.

Q: Can I customize the toast appearance? A: Yes. Pass style, className, or a custom render function. For full control, use the headless useToaster() hook and build your own UI.

Q: Does it support dark mode? A: The default theme follows system preferences. You can override colors via the style prop or className for manual dark mode control.

Sources

• https://github.com/timolins/react-hot-toast
• https://react-hot-toast.com/