React clever Toast 🧠✨

React clever Toast the toast that thinks for you.
Lightweight, accessible, and auto-verifying toast notifications for React apps. toast.auto() analyzes what you pass (string, Error, response like objects, or plain objects) and shows the most appropriate toast (success, error, info, warning) — no manual type selection required.

Table of contents

• React clever Toast 🧠✨
  • Table of contents
  • Why use React clever Toast
  • Features
  • Installation
  • Quick start
  • API
    • useToast() (hook)
    • ToastProvider
    • ToastContainer (props)
  • Auto-detection — how toast.auto decides
  • Customization & Extensibility
  • Examples

Why use React clever Toast

• Saves developers time: you don't need to decide success vs error manually, call toast.auto() with whatever you have.
• Works well for dashboards, admin apps, or any app that handles API responses.
• Small, customizable, and easy to theme with Tailwind.
• No external animation libraries required built with Tailwind (configurable).
• Extensible detectors: you can tweak how messages are classified.

Features

• toast.success() / toast.error() / toast.info() / toast.warning() — explicit calls
• toast.auto(input) — clever one-liner that decides type + message
• Configurable ToastContainer (position, text color, shadow, border radius)
• Built-in entry + exit animations (a few preset styles)
• Modular detectors (string, error, object, optional warning/info detectors)
• Accessible (aria-live alerts)

Installation

Peer dependencies: this is a React library make sure your project has React 18+ installed.

# Using yarn
yarn add react-clever-toast

# or npm
npm install react-clever-toast

If you are developing / building the package locally, use yarn dev in the library project to preview the demo.

The library expects consumers to provide React as a peer dependency.
If you use TypeScript, types are exported in the dist bundle.

Quick start

Wrap your app with ToastProvider and render ToastContainer once (usually near the root).

// App.tsx
import React from "react";
import { ToastProvider } from "react-clever-toast";
import ToastContainer from "react-clever-toast/ToastContainer"; // adjust import path per published package
import Demo from "./Demo";

export default function App() {
  return (
    <ToastProvider>
      <Demo />
      <ToastContainer />
    </ToastProvider>
  );
}

Use the hook anywhere inside the provider:

// Demo.tsx
import React from "react";
import { useToast } from "react-clever-toast";

export default function Demo() {
  const toast = useToast();

  return (
    <div>
      <button onClick={() => toast.success("Saved successfully!")}>Success</button>
      <button onClick={() => toast.error("Something failed")}>Error</button>
      <button onClick={() => toast.auto({ message: "Profile updated" })}>Auto (object)</button>
      <button onClick={() => toast.auto("File uploaded successfully!")}>Auto (string)</button>
      <button onClick={() => toast.auto(new Error("Network error"))}>Auto (Error)</button>
    </div>
  );
}

API

useToast() (hook)

Returns an object with these functions:

const { success, error, info, warning, auto } = useToast();

• success(message: string, duration?: number) — show success toast
• error(message: string, duration?: number) — show error toast
• info(message: string, duration?: number) — show info toast
• warning(message: string, duration?: number) — show warning toast
• auto(input: any, duration?: number) — cleverly detect and show toast based on input. Returns { type, message } for optional diagnostics.

ToastProvider

Wrap your app root. The provider contains the internal toast state and manages lifecycle.

<ToastProvider>{children}</ToastProvider>

ToastContainer (props)

Renders toasts and accepts customization props:

<ToastContainer
  position="top-right"
  animationStyle="slideIn"
  textColor="white"
  textColorWeight="500"
  shadowSize="md"
  roundedSize="lg"
/>

Auto-detection — how toast.auto decides

toast.auto() runs the input through detectors in this order:

1. Error detector
2. Success detector
3. Warning detector
4. Info detector
5. String detector
6. Fallback (info)

Customization & Extensibility

Supports animations: "fadeIn", "slideIn", "scaleIn", "bounceIn"
Positions: "top-right", "top-left", "bottom-right", "bottom-left"

Examples

toast.auto({ success: true, message: "User created" }); // success
toast.auto({ error: "Unauthorized" }); // error
toast.auto(new Error("Network failed")); // error
toast.auto("Upload complete!"); // success