Quick answer

react-hot-toast is a lightweight React notification library that provides a simple API (toast, toast.promise, Toaster) for creating non-blocking toast messages. Install with npm i react-hot-toast, add <Toaster /> to your app root, then call toast('message') or toast.success('ok').

If you want a step-by-step walkthrough, read the sections below — examples included.

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

Next, mount the global <Toaster /> component in your app root (e.g., inside App.jsx or a layout wrapper). This component renders the toast container and accepts global options.

Example minimal setup — keep this near your top-level component so all routes/components can trigger toasts:

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

export default function App() {
  return (
    <>
      <Toaster position="top-right" />
      {/* rest of your app */}
    
  )
}

Need a guided tutorial? See this practical walkthrough on Dev.to: react-hot-toast tutorial.

Core concepts & API

react-hot-toast exposes a few simple primitives: the default export toast, the Toaster component, and optional hooks like useToaster for advanced control. The API is intentionally small: show, update, and dismiss toasts.

Basic methods include toast('message'), toast.success('ok'), toast.error('err'), and toast.dismiss(id). Each toast returns an ID which you can use to update or close the toast later.

For more advanced use, toast.promise(promise, { loading, success, error }) ties toast states to a Promise lifecycle, automatically switching messages as the promise resolves or rejects — very handy for network requests and async actions.

Basic examples: toast messages and hooks

Here's a compact example showing how to trigger success and error notifications from a button click:

import toast from 'react-hot-toast'

function SaveButton() {
  const handleSave = async () => {
    const id = toast.loading('Saving...')
    try {
      await api.saveData()
      toast.success('Saved!', { id }) // updates the same toast
    } catch (err) {
      toast.error('Save failed', { id })
    }
  }

  return <button onClick={handleSave}>Save</button>
}

This pattern avoids stacking multiple loading toasts for the same action and provides a smooth UX. The optional id parameter means you update the existing toast instead of creating a new one.

If you need programmatic inspection or rendering control, use the internal hook: const { toasts } = useToaster(). That gives you the list of active toasts for custom UIs or telemetry.

Promises & async flows (toast.promise)

react-hot-toast shines when handling async operations. The toast.promise helper automates loading➜success➜error transitions so your code stays focused:

// returns a promise from some async operation
toast.promise(
  fetchData(),
  {
    loading: 'Fetching data...',
    success: 'Data fetched successfully 👌',
    error: 'Failed to fetch data 🤯'
  }
)

Under the hood it shows the loading state immediately, then updates the same toast to success or error depending on the result. This reduces visual flicker and keeps the UI predictable for users and screen readers.

Use the API when you have network calls, form submissions, or any promise-based task. It’s concise and prevents boilerplate for manually creating and dismissing toasts around async code.

Customization & styling

There are two main ways to customize the look and behavior of your toasts: global options on <Toaster /> and per-toast options passed to toast(). Global options include position, default duration, and default styles or class names.

Example: global toast options for a theme and accessibility props:

<Toaster
  position="bottom-left"
  toastOptions={{
    duration: 4000,
    style: { background: '#0f172a', color: '#fff' },
    ariaProps: { role: 'status' }
  }}
/>

For bespoke UI, you can render a React component for a toast using toast.custom or the render function signature (version-dependent). This allows you to create richer content (buttons, progress bars) inside toasts.

Accessibility & best practices

Toasts are ephemeral, so accessibility matters: set ariaProps on your Toaster or individual toasts, and avoid critical content solely inside toasts. For status messages, use role="status" so screen readers announce updates.

Keep messages short and actionable. If an action requires more context (like undo), include a clear affordance inside the toast (button or link) rather than burying details in long text.

Also, mind timings: short success messages (1.5–3s) vs. longer error messages that need user acknowledgement. Allow touch targets and keyboard focus where you include interactive controls in a toast.

Troubleshooting & tips

If toasts don't appear, confirm that <Toaster /> is rendered once at the top level. Multiple Toaster instances can behave unexpectedly. Also verify imports: import toast, { Toaster } from 'react-hot-toast'.

To prevent duplicate toasts, reuse an ID or conditionally call toast. For server-side rendering, render <Toaster /> client-side only or guard with a mounted check.

When upgrading between library major versions, check changelogs — some APIs (like toast.custom vs. render callbacks) may change. The official docs are the source of truth.

Links & resources

Official docs: react-hot-toast — the authoritative reference for options, types, and examples.

Source & issues: react-hot-toast on GitHub — report bugs or explore the codebase.

Community tutorial: react-hot-toast tutorial for a practical build-up and example project.

Semantic core (grouped keywords)

Primary

react-hot-toast
React toast notifications
React notification library

Secondary

react-hot-toast installation
react-hot-toast example
react-hot-toast setup
React toast messages
react-hot-toast promise

Clarifying / LSI

react-toast hooks
React alert notifications
React notification system
react-hot-toast customization
React toast library
react-hot-toast getting started

FAQ

1. How do I install and get started with react-hot-toast?

Install with npm i react-hot-toast or yarn add react-hot-toast. Import Toaster at the app root and add <Toaster />. Trigger toasts with toast('message'), toast.success('ok'), or toast.error('err'). See the official docs for more options: react-hot-toast.

2. How do I show a toast for an async operation?

Use toast.promise(promise, { loading, success, error }). It displays a loading message immediately and replaces it with success or error once the promise resolves or rejects. This keeps the UI clean and prevents stacking multiple toasts for the same operation.

3. How can I customize toast styles and positions?

Customize globally via <Toaster toastOptions={{ style, duration, position }} /> or per-toast by passing options to toast(). For complex layouts, render a custom React component inside the toast using the library’s render/custom API.

Suggested micro-markup

Add the JSON-LD FAQ (included above) to improve eligibility for rich results and voice search snippets. For article-level markup, add Article schema with headline, description, author, and datePublished if desired.

Backlinks (keyword anchors)

Reference links used in this article:

• React toast library
• react-hot-toast GitHub
• react-hot-toast tutorial