Toaster - Simple Toast Notification Library

A lightweight, customizable toast notification library for both vanilla JavaScript and React applications.

Features

• 🚀 Lightweight - No heavy dependencies
• 🎨 Customizable - Easy to style and configure
• ⚛️ React Support - Includes React hooks and provider
• 📱 Responsive - Works on all screen sizes
• 🎯 TypeScript - Full TypeScript support
• 🎪 Multiple Positions - 6 different toast positions
• ⏱️ Auto-dismiss - Configurable duration
• 🎭 Multiple Types - Success, error, info, warning, and custom

Installation

npm install toaster

Usage

Vanilla JavaScript

import { toast } from "toaster";

// Basic usage
toast.success("Operation completed successfully!");
toast.error("Something went wrong!");
toast.info("Here is some information");
toast.warning("Please be careful");

// Custom toast
toast.show("Custom message", {
  backgroundColor: "#6366f1",
  duration: 5000,
  position: "bottom-center",
});

// Clear all toasts
toast.clearAll();

React

import React from "react";
import { ToastProvider, useToast } from "toaster/react";

function App() {
  return (
    <ToastProvider>
      <MyComponent />
    </ToastProvider>
  );
}

function MyComponent() {
  const toast = useToast();

  const handleSuccess = () => {
    toast.success("Operation completed!");
  };

  const handleError = () => {
    toast.error("Something went wrong!");
  };

  return (
    <div>
      <button onClick={handleSuccess}>Show Success</button>
      <button onClick={handleError}>Show Error</button>
    </div>
  );
}

API Reference

Vanilla JavaScript API

toast.success(message, options?)

Shows a success toast notification.

toast.error(message, options?)

Shows an error toast notification.

toast.info(message, options?)

Shows an info toast notification.

toast.warning(message, options?)

Shows a warning toast notification.

toast.show(message, options?)

Shows a custom toast notification.

toast.clearAll()

Removes all active toast notifications.

toast.setDefaultOptions(options)

Sets default options for all future toasts.

React API

ToastProvider

React context provider that wraps your app.

Props:

• children - React children
• config - Configuration object (optional)

useToast()

React hook that returns toast methods.

Returns:

• success(message, options?) - Show success toast
• error(message, options?) - Show error toast
• info(message, options?) - Show info toast
• warning(message, options?) - Show warning toast
• show(message, options?) - Show custom toast
• clearAll() - Clear all toasts
• removeToast(id) - Remove specific toast

Toast Options

interface ToastOptions {
  duration?: number; // Duration in milliseconds (default: 3000)
  position?: ToastPosition; // Position on screen (default: 'top-right')
  icon?: string | HTMLElement; // Custom icon
  backgroundColor?: string; // Custom background color
  textColor?: string; // Custom text color
  className?: string; // Additional CSS classes
  style?: Partial<CSSStyleDeclaration>; // Custom CSS styles
  onClick?: () => void; // Click callback
  onClose?: () => void; // Close callback
}

Toast Positions

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

Toast Types

• 'success' - Green background
• 'error' - Red background
• 'info' - Blue background
• 'warning' - Orange background
• 'custom' - Custom styling

Configuration

React Provider Configuration

<ToastProvider
  config={{
    defaultDuration: 5000,
    defaultPosition: "bottom-center",
    maxWidth: "500px",
    minWidth: "350px",
    spacing: "12px",
    borderRadius: "12px",
    fontSize: "16px",
    fontFamily: "Arial, sans-serif",
    zIndex: 9999,
    customVariables: {
      "--toast-success-bg": "#059669",
      "--toast-error-bg": "#dc2626",
    },
  }}
>
  <App />
</ToastProvider>

CSS Customization

The library uses CSS custom properties for easy styling:

:root {
  --toast-success-bg: #10b981;
  --toast-error-bg: #ef4444;
  --toast-info-bg: #3b82f6;
  --toast-warning-bg: #f59e0b;
  --toast-text-color: #ffffff;
  --toast-border-radius: 8px;
  --toast-padding: 12px 16px;
  --toast-font-size: 14px;
  --toast-font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
    "Helvetica Neue", Arial, sans-serif;
  --toast-box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
  --toast-z-index: 10000;
  --toast-spacing: 8px;
  --toast-max-width: 400px;
  --toast-min-width: 300px;
}

License

MIT