Getting started — installation and setup

If you want a zero-config toast system that works in functional components and plays nicely with hooks, start with react-hot-toast. The quickest path is installing from npm or yarn and placing a single <Toaster /> at the top level of your React tree so notifications can be rendered anywhere.

Run one of these commands to install:

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

Then add the provider and call a toast from any component. Example:

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

function App(){ 
  return (
    <>
      
       toast('Hello from react-hot-toast!')}>Notify
    
  );
}

For a concise tutorial and practical examples, see this react-hot-toast tutorial and setup guide on Dev.to — it walks through installation, examples, and advanced usage with clear code snippets. (link: react-hot-toast tutorial).

Core concepts and common APIs

react-hot-toast exposes a few simple APIs: toast() to show a message, toast.success() and toast.error() for semantic variants, toast.custom() for full JSX control, and toast.promise() for async flows. The library’s design emphasizes small bundle size and minimal runtime overhead.

Options are passed inline to control duration, position, and styling. For example:

toast('Saved', { duration: 4000, position: 'top-right' });
toast.success('Completed', { style: { background: '#0f0' } });

Hooks aren’t required because the API is global and works in any component, but you can integrate it with your custom hooks to encapsulate notification logic. If you prefer typed notifications or cross-component handling, wrap calls in helper functions—this keeps your UI components free of notification logic.

Examples: synchronous toasts, promise integration, and custom JSX

Simple toast usage is straightforward: call toast('message'). For async operations use toast.promise() to automatically show pending, success, and error states tied to a Promise. This pattern removes boilerplate and improves UX for network requests and long-running tasks.

Example with toast.promise:

const fetchData = () => fetch('/api/data').then(r => r.json());

toast.promise(
  fetchData(),
  {
    pending: 'Fetching data...',
    success: 'Data loaded 👌',
    error: 'Error loading data 🤯',
  }
);

For fully custom looks or interactive toasts, use toast.custom() to supply JSX. This lets you include buttons, links, or progress bars inside the toast while keeping accessibility and dismiss behavior consistent with the library.

Need a working example? Check the step-by-step react-hot-toast example in the practical guide on Dev.to — it demonstrates promise handling, custom toasts, and integration patterns: react-hot-toast example.

Customization, theming, and accessibility

Customizing appearance is flexible: pass a style object, use CSS overrides, or supply a custom component. You can control animation classes, duration, and position. For consistency across your app, centralize toast styles in a theme or helper wrapper that calls toast() with your defaults.

Accessibility matters: include ARIA attributes in custom JSX if you’re rendering interactive content. The default toasts are announced by screen readers when they appear; if you add complex children, validate the announcements using assistive technology or automated checks.

Animations are CSS-driven for performance; you can replace or tune them with CSS variables or classes to keep motion preferences in mind. For apps with reduced-motion settings, prefer subtle fades or allow users to disable animations entirely via a global setting.

Advanced patterns and best practices

Use toast IDs to update or dismiss specific notifications: save the return value of toast() and call toast.dismiss(id) or toast.success(id) to replace content. This is useful for long-running processes where you want to swap a “loading” toast with a “complete” toast instead of stacking multiple messages.

Integrate with state management by wrapping notification calls in effects or middleware rather than sprinkling toast calls throughout components. For example, trigger notifications in your request layer or in Redux/React Query callbacks so UI components stay focused on rendering.

Performance tip: because react-hot-toast renders to a portal, it doesn’t force re-renders of your entire app when new toasts appear. However, avoid creating large JSX blobs in toast.custom() that reference heavy state—use lightweight components or lazy-load heavy content when necessary.

Troubleshooting & server-side considerations

react-hot-toast is client-side only. For server-rendered apps, render the <Toaster /> on the client and avoid calling toast during SSR. Use hydration-safe patterns: trigger toasts inside useEffect or in response to client actions.

If toasts don’t appear, confirm that <Toaster /> is included once at the app root and that you haven’t accidentally shadowed the toast import. Also check CSS specificity if default styles are not visible—custom resets can hide the library’s base styles.

When testing, mock toast calls or assert side effects by checking for the presence of the toast container. For accessibility testing, verify screen-reader announcements and keyboard dismiss behavior across browsers and assistive tech.

Semantic core (keywords & clusters)

Backlinks and further reading

Practical walkthroughs and examples: the Dev.to tutorial provides an end-to-end walkthrough and code samples for building notification systems with react-hot-toast. Read the guide here: react-hot-toast tutorial.

Reference the guide when implementing installation and example flows: react-hot-toast installation & example contains practical snippets for both beginners and advanced users.

FAQ

How do I install and set up react-hot-toast?

Install with npm i react-hot-toast or yarn add react-hot-toast, add <Toaster /> at your app root, and call toast('Message') in components. For step-by-step examples and setup tips, consult the detailed tutorial: react-hot-toast setup.

How do I use toast.promise with async operations?

Wrap a Promise in toast.promise(promise, { pending, success, error }). The library shows the pending message immediately and replaces it with success or error based on the promise outcome. This pattern reduces boilerplate and keeps the UX consistent.

How can I customize appearance and behavior of toasts?

Pass options to toast() (duration, position, style), use toast.custom() for full JSX control, or centralize defaults in a helper wrapper. Respect reduced-motion preferences and test screen-reader announcements when adding interactive content.