@aminekun90/react-toast 🍞

A lightweight, high-performance, and Hook-based toast notification library for React 18 & 19.

Demo app

View React Demo

Shares its core engine and stylesheet with the Angular library @aminekun90/ngx-toast — identical behavior and themes.

Key Features

• ⚛️ React 18 & 19 Ready: Full support for Concurrent Mode and the latest React features.
• ⚓ Hook-based API: Simple and intuitive useToast() hook to trigger notifications.
• 🎨 FontAwesome Integration: Professional iconography baked-in.
• ♿ Accessible: role="alert", aria-live, keyboard dismissal (Enter/Space/Escape), focus styles.
• ⏸️ Pause on hover: Timer and progress bar pause while hovered/focused.
• 🌙 Themes & dark mode: 5 built-in themes, full CSS-variable customization, automatic dark mode.
• 🧩 Global defaults: Configure position, duration, max stack, dedup via <ToastProvider config>.
• 🔁 Promise & loading toasts: loading() and promise() helpers that swap in place.
• 📦 Tiny: Small bundle, optimized with Vite, zero extra runtime deps.

Installation

Install the package via Yarn:

yarn add @aminekun90/react-toast

Peer Dependencies

Ensure you have the following dependencies installed (required for icons and peer-matching):

yarn add @fortawesome/react-fontawesome @fortawesome/fontawesome-svg-core @fortawesome/free-solid-svg-icons

Configuration

Wrap your application (or the desired part of your tree) with the ToastProvider.

import { ToastProvider } from '@aminekun90/react-toast';

export function App() {
  return (
    <ToastProvider> <!-- Mandatory -->
      <MyMainComponent />
    </ToastProvider>
  );
}

Usage

1. Add the Global Container

Place the ToastContainer at the root of your application (usually in App.tsx). It will manage the stacking of all active notifications.

import { ToastContainer } from '@aminekun90/react-toast';

export default function App() {
  return (
    <div className="app-root">
      <ToastContainer />
      <MyContent />
    </div>
  );
}

2. Triggering Notifications

Use the useToast hook anywhere inside your ToastProvider.

import { useToast } from '@aminekun90/react-toast';

export function MyComponent() {
  const { success, error, info, warning } = useToast();

  const handleAction = () => {
    success('Operation successful!', 'Success');
  };

  return <button onClick={handleAction}>Click me</button>;
}

3. Global defaults (optional)

<ToastProvider config={{
  position: 'top-right',
  duration: 4000,
  pauseOnHover: true,
  maxToasts: 5,
  preventDuplicates: true,
  newestOnTop: true,
}}>
  <App />
</ToastProvider>

4. Loading & Promise toasts

const { loading, success, promise } = useToast();

const id = loading('Uploading…');
// later: success('Done!', undefined, { id });

await promise(saveUser(), {
  loading: 'Saving…',
  success: (user) => `Saved ${user.name}`,
  error: (err) => `Failed: ${err}`,
});

API Reference

ToastConfig Properties

Theming

Five built-in themes, applied per toast or globally; everything is CSS-variable driven for full customization.

success('Saved!', undefined, { theme: 'glass' });

<body class="ngx-toast-theme-material">…</body>

📖 Full reference: docs/THEMING.md · 🏗️ docs/ARCHITECTURE.md

Compatibility

Keep this project alive :coffee:

I dedicate time and effort to maintaining this library. If it helped you, please consider donating!

Donate via PayPal

License

MIT License, By Amine Bouzahar.