React Toast

A lightweight, zero-dependency React toast notification library built with React, TypeScript, Vite, and Tailwind CSS.

Features

• 🚀 Zero dependencies (except React peer deps)
• 🎯 Call toast() from anywhere - even outside React components
• ⚡ Two usage modes: Component (<Toaster />) or Programmatic API
• 🎨 Tailwind CSS styling - no inline styles
• 📦 Tiny bundle size
• 🔥 SSR safe
• 💪 TypeScript support
• 🎭 Beautiful animations
• 🎨 Customizable colors and positions
• 🚫 No React Context/Provider required

Installation

npm install react-toast-notification-aayan

Setup

There are two ways to use this library:

Option 1: Using the <Toaster /> Component (Recommended)

Import the CSS and add the <Toaster /> component to your app:

import { Toaster, toast } from 'react-toast-notification-aayan';
import 'react-toast-notification-aayan/styles.css';

function App() {
  return (
    <>
      <Toaster />
      {/* Your app content */}
      <button onClick={() => toast.success('Hello!')}>
        Show Toast
      </button>
    </>
  );
}

Option 2: Programmatic API (No Component Required)

Just import the CSS - the toast container will be automatically created:

import { toast } from 'react-toast-notification-aayan';
import 'react-toast-notification-aayan/styles.css';

function App() {
  return (
    <button onClick={() => toast.success('Hello!')}>
      Show Toast
    </button>
  );
}

Note: Both approaches work perfectly! Use whichever fits your needs better.

Usage

Basic Usage

import { toast } from 'react-toast-notification-aayan';

// Simple toast
toast('Hello World!');

// With options
toast('Custom toast', {
  duration: 5000,
  position: 'top-right',
  color: 'success',
  closable: true
});

Toast Types

// Success
toast.success('Operation successful!');

// Error
toast.error('Something went wrong!');

// Info
toast.info('Here is some information');

// Warning
toast.warning('Please be careful!');

Dismissing Toasts

// Manual dismiss
const id = toast('This can be dismissed');
toast.dismiss(id);

// Clear all toasts
toast.clear();

Options

interface ToastOptions {
  duration?: number;        // Auto-dismiss time in ms (default: 3000, 0 = no auto-dismiss)
  position?: ToastPosition; // 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left'
  color?: ToastColor;       // 'success' | 'error' | 'info' | 'warning' | custom
  closable?: boolean;       // Show close button (default: true)
  className?: string;       // Additional CSS classes
}

Positions

• top-right (default)
• top-left
• bottom-right
• bottom-left

Custom Colors

toast('Custom color toast', {
  color: 'purple' // Will use bg-purple-500
});

Complete Example with <Toaster />

import { Toaster, toast } from 'react-toast-notification-aayan';
import 'react-toast-notification-aayan/styles.css';

function App() {
  const handleSuccess = () => {
    toast.success('Data saved successfully!');
  };

  const handleError = () => {
    toast.error('An error occurred!');
  };

  const handleCustom = () => {
    toast('Custom message', {
      duration: 5000,
      position: 'bottom-left',
      color: 'purple',
      closable: true
    });
  };

  return (
    <>
      <Toaster />
      <div className="p-4">
        <button onClick={handleSuccess}>Show Success</button>
        <button onClick={handleError}>Show Error</button>
        <button onClick={handleCustom}>Show Custom</button>
      </div>
    </>
  );
}

export default App;

Use Anywhere

Works in React components:

import { Toaster, toast } from 'react-toast-notification-aayan';

function MyComponent() {
  return (
    <button onClick={() => toast.success('Clicked!')}>
      Click me
    </button>
  );
}

Works outside React:

// In a utility function
export function saveData() {
  try {
    // Save logic
    toast.success('Data saved!');
  } catch (error) {
    toast.error('Failed to save');
  }
}

// In an API client
fetch('/api/data')
  .then(() => toast.success('Data loaded'))
  .catch(() => toast.error('Load failed'));

API Reference

<Toaster />

The main component to render the toast container in your app.

import { Toaster } from 'react-toast-notification-aayan';

function App() {
  return (
    <>
      <Toaster />
      {/* Your app content */}
    </>
  );
}

Note: You only need to include <Toaster /> once in your app, typically in your root component.

toast(message, options?)

Shows a toast notification.

Returns: string - Toast ID

toast.success(message, options?)

Shows a success toast.

Returns: string - Toast ID

toast.error(message, options?)

Shows an error toast.

Returns: string - Toast ID

toast.info(message, options?)

Shows an info toast.

Returns: string - Toast ID

toast.warning(message, options?)

Shows a warning toast.

Returns: string - Toast ID

toast.dismiss(id)

Dismisses a specific toast.

Parameters:

• id: string - Toast ID returned from toast()

toast.clear()

Clears all toasts.

Architecture

• Two Usage Modes:
  • Component Mode: Use <Toaster /> for declarative React approach
  • Programmatic Mode: Auto-mounting container for imperative usage
• Global Store: Toast state managed outside React (no React imports in store)
• Auto-mounting: Container automatically mounts on first toast (programmatic mode)
• Auto-unmounting: Container unmounts when no toasts remain (programmatic mode)
• Single Root: Reuses same React root for efficiency
• SSR Safe: No window/document access at import time
• Portal-based: Renders at document body level (programmatic mode) or inline (component mode)

Why Two Usage Modes?

Use <Toaster /> when:

• You prefer declarative React patterns
• You want full control over where toasts render
• You're building a component-based architecture

Use Programmatic API when:

• You need to call toasts from non-React code
• You want the simplest possible setup
• You're migrating from another toast library

Both modes can be used together seamlessly!

Development

# Install dependencies
npm install

# Build
npm run build

# Dev mode
npm run dev

License

MIT

customToastNPM