React Hot Toast

react-hot-toast is a lightweight notification library for React that renders customizable toast messages with sensible defaults for animation, positioning, and accessibility. It ships a single <Toaster /> component paired with an imperative toast() API, so triggering a notification from anywhere in your component tree requires no context providers, reducers, or global state wiring of your own.

Beyond basic toasts, it includes first-class support for promise-based flows via toast.promise(), which automatically transitions a toast between loading, success, and error states as an async operation resolves. The entire library — including its CSS-in-JS styling — is under 5kb, and a headless build (react-hot-toast/headless) exposes the same toast store without any bundled markup or styles for teams that want to render toasts with their own UI.

What You Get

• A single <Toaster /> component that renders and positions all active toasts, with configurable placement (top-center, bottom-right, etc.), gutter spacing, and hover-to-pause behavior
• An imperative toast() API with typed shorthand methods (toast.success, toast.error, toast.loading, toast.custom) plus toast.promise() for automatic loading/success/error transitions
• Built-in accessibility via ARIA live-region props on every toast, and automatic respect for prefers-reduced-motion
• A headless entry point (react-hot-toast/headless) exposing the same store and hooks without any bundled styles, for fully custom toast UIs
• Multi-toaster support via a toasterId, letting different parts of an app render independent toast stacks

Common Use Cases

• Confirming a successful form submission or save action with a brief, auto-dismissing toast
• Surfacing API/network errors inline without redirecting the user or blocking the UI with a modal
• Wrapping an async request (upload, mutation, fetch) in toast.promise() to show a single toast that morphs from loading to success/error
• Building fully custom notification UI (branded styling, action buttons) on top of the headless store while keeping the timing/dismiss logic from the library

Under The Hood

Architecture — react-hot-toast is a React notification library built around three layers: a plain-object reducer/store (src/core/store.ts) that maintains toast state per “toaster ID” outside of React (module-level memoryState + listeners array), a toast() API surface (src/core/toast.ts) that dispatches actions (ADD_TOAST/UPSERT_TOAST/DISMISS_TOAST/REMOVE_TOAST) to that store, and a presentation layer (src/components/toaster.tsx, toast-bar.tsx, toast-icon.tsx) that subscribes via a useStore/useToaster hook and renders positioned toast elements using goober for CSS-in-JS styling and a MutationObserver-driven height-measurement callback (ToastWrapper) to compute stacking offsets without layout thrash. Pause/resume timers for hover are modeled as actions (START_PAUSE/END_PAUSE) that adjust each toast’s pauseDuration, keeping timing logic pure and testable in the reducer rather than scattered through components. The headless subpath entry (src/headless/index.ts) re-exports the same store/hooks without the styled components, letting consumers build a fully custom UI on the same state engine.

Tech Stack — TypeScript throughout (66% of repo bytes per GitHub language stats), bundled with tsup (dual CJS/ESM output plus type declarations, confirmed by the exports map in package.json), styled via goober (a ~1KB CSS-in-JS library) rather than a heavier styling dependency, and only two runtime dependencies (csstype, goober) — deliberately minimal given the “less than 5kb including styles” claim in the README, enforced by a size-limit config with per-bundle KB budgets. react/react-dom are peer dependencies (>=16), and a documentation site lives in site/ built with MDX content, separate from the library’s own build.

Code Quality — test/toast.test.tsx (534 lines) exercises the public toast API against a rendered <Toaster /> using @testing-library/react and Jest fake timers, covering dismiss/remove flows, promise-based toasts, and timing-sensitive behavior (a waitTime helper advancing jest.advanceTimersByTime) — the fake-timer discipline in beforeEach/afterEach (resetting all toasts, restoring real timers) suggests real attention to test isolation given the module-level mutable store. The source itself keeps functions small and single-purpose (the reducer in store.ts is a pure switch statement with no side effects), and naming is consistent (an ActionType enum, Toast/ToasterProps types collected in a single types.ts). No end-to-end or visual regression tests exist for the styled components — only behavioral/unit-level coverage.

API Design — The default export doubles as both a callable function (toast(message)) and a namespace of methods (toast.success, toast.error, toast.loading, toast.custom, toast.dismiss, toast.promise), which is a low-ceremony, highly discoverable pattern — a working toast requires exactly one <Toaster /> mounted plus a single toast(‘message’) call, per the README’s own quick-start. toast.promise() in particular collapses a common three-state UI pattern (loading/success/error) into one call. The headless export path is a deliberate extensibility seam for teams that want the state machine without the bundled UI/CSS.