Documentation

Complete guide to using ToastOnSteroid - a modern, customizable toast notification system for React applications with beautiful animations.

Installation

Get started with ToastOnSteroid in your project

Install via npm

npm install toastonstaroid

Peer Dependencies

npm install toastonstaroid --legacy-peer-deps

Quick Start

Get up and running in 3 simple steps

Add ToastContainer to your App

import { ToastContainer } from "toastonstaroid";

function App() {
  return (
    <>
      <YourApp />
      <ToastContainer position="bottom-right" />
    </>
  );
}

Import the toast function

import { toast } from "toastonstaroid";

Use toast methods

const handleClick = () => {
  toast.success("Operation completed successfully!");
  
  // Other variants:
  toast.fire("Critical alert!");
  toast.rain("New message received");
  toast.smoke("Settings saved");
  toast.cyberpunk("System initialized");
  toast.dragonball("Power level over 9000!");
  toast.waterflow("Changes saved successfully");
};

Basic Usage

Examples of different toast types

success

toast.success("Operation completed successfully!");

error

toast.error("Failed to save changes!");

warning

toast.warning("This action cannot be undone!");

info

toast.info("New update available!");

fire

toast.fire("Critical system alert!");

rain

toast.rain("New message received!");

smoke

toast.smoke("Settings saved successfully!");

cyberpunk

toast.cyberpunk("System initialized!");

dragonball

toast.dragonball("Power level over 9000!");

waterflow

toast.waterflow("Changes saved successfully!");

ToastContainer Props

Configure the toast container behavior and appearance

Prop	Type	Default	Description
position	string	"top-right"	Position of the toast container
autoClose	number	3000	Auto close timeout in milliseconds (0 to disable)
closeOnClick	boolean	true	Close toast when clicked
pauseOnHover	boolean	true	Pause toast timer on hover
className	string	""	Additional CSS class for the container
style	object	{}	Inline styles for the container

// Available positions:
"top-right" | "top-left" | "top-center" | 
"bottom-right" | "bottom-left" | "bottom-center"

Toast Methods

Available methods for showing different types of toasts

// Basic toast types
toast.success(message: string, options?: ToastOptions): string;
toast.error(message: string, options?: ToastOptions): string;
toast.warning(message: string, options?: ToastOptions): string;
toast.info(message: string, options?: ToastOptions): string;

// Animated variants
toast.fire(message: string, options?: ToastOptions): string;
toast.rain(message: string, options?: ToastOptions): string;
toast.smoke(message: string, options?: ToastOptions): string;
toast.cyberpunk(message: string, options?: ToastOptions): string;
toast.dragonball(message: string, options?: ToastOptions): string;
toast.waterflow(message: string, options?: ToastOptions): string;

// Control methods
toast.dismiss(toastId: string): void;
toast.dismissAll(): void;
toast.update(toastId: string, options: ToastOptions): void;

Configuration Options

Customize toast behavior and appearance

Option	Type	Default	Description
toastId	string	Random ID	Custom ID for the toast
duration	number	3000	Display duration in ms
onClose	() => void	-	Callback when toast closes
className	string	-	Additional CSS class
style	object	-	Inline styles

// Example with options
toast.success("Profile updated!", {
  duration: 5000,
  className: "custom-toast",
  style: { backgroundColor: "#4ade80" },
  onClose: () => console.log("Toast closed")
});

Toast Variants

Choose between different visual styles and animations

Basic Variants

Simple yet modern design with smooth animations.

success: Green background
error: Red background
warning: Orange background
info: Blue background

Animated Variants

Special effects powered by GSAP animations.

fire: Fiery animation
rain: Rain effect
smoke: Smoke effect
cyberpunk: Futuristic style
dragonball: Anime-inspired
waterflow: Smooth water animation

Custom Styling

Customize the appearance of your toasts

Using CSS Variables

Override default styles using CSS variables:

:root {
  --toast-bg: rgba(30, 41, 59, 0.95);
  --toast-text: #ffffff;
  --toast-border: rgba(255, 255, 255, 0.1);
  --toast-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
  --toast-padding: 12px 16px;
  --toast-spacing: 16px;
  --toast-border-radius: 8px;
  --toast-font-size: 14px;
  --toast-icon-size: 20px;
}

Custom Class Names

Apply custom class names for complete control:

// Custom container class
<ToastContainer className="custom-container" />

// Custom toast class
toast.success("Message", {
  className: "custom-toast success-toast"
});

// CSS example
.custom-toast {
  background: linear-gradient(135deg, #4361ee, #3a0ca3);
  border: 1px solid rgba(255, 255, 255, 0.2);
  backdrop-filter: blur(10px);
  border-radius: 12px;
}

.success-toast {
  border-left: 4px solid #4ade80;
}

Inline Styles

Apply styles directly through props:

// Container styles
<ToastContainer 
  style={{
    top: '2rem',
    right: '2rem',
    zIndex: 10000
  }} 
/>

// Toast styles
toast.success("Profile updated!", {
  style: {
    backgroundColor: '#4ade80',
    color: '#fff',
    border: '1px solid #22c55e'
  }
});

Positioning

Configure where toasts appear on screen

top-right

position="top-right"

top-center

position="top-center"

top-left

position="top-left"

bottom-right

position="bottom-right"

bottom-center

position="bottom-center"

bottom-left

position="bottom-left"

Responsive Positioning

Position toasts differently based on screen size:

// Mobile: bottom-center, Desktop: top-right
const [position, setPosition] = useState('bottom-center');

useEffect(() => {
  const handleResize = () => {
    setPosition(window.innerWidth < 768 ? 'bottom-center' : 'top-right');
  };
  
  window.addEventListener('resize', handleResize);
  handleResize();
  
  return () => window.removeEventListener('resize', handleResize);
}, []);

return <ToastContainer position={position} />;

Advanced Offset Configuration

Fine-tune toast position with pixel offsets:

<ToastContainer 
  position="top-right"
  style={{
    top: '80px',   // Below navbar
    right: '20px',
    left: 'auto',  // Reset left position
    bottom: 'auto' // Reset bottom position
  }}
/>

Best Practices

Guidelines for effective toast usage

Message Duration

• Success messages: 3-5 seconds
• Error messages: 5-7 seconds
• Warning messages: 4-6 seconds
• Info messages: 3-5 seconds
• Animated variants: 4-6 seconds

Positioning

• Use bottom positions for less intrusive notifications
• Use top positions for critical alerts
• Consider mobile responsiveness
• Avoid covering important UI elements

Programmatic Control

Advanced control over toast notifications

Dismiss Specific Toast

const toastId = toast.info("Processing...", 0);

// Later...
toast.dismiss(toastId);

Dismiss All Toasts

toast.dismissAll();

Update Existing Toast

const toastId = toast.loading("Saving...");

// After save completes
toast.update(toastId, {
  render: "Saved successfully!",
  type: "success",
  autoClose: 3000
});

Troubleshooting

Solutions for common issues

Toasts not showing?

Ensure ToastContainer is rendered in your app
Check for z-index conflicts (default z-index: 9999)
Verify no overflow: hidden is hiding toasts
Confirm you're importing from "toastonstaroid"

Animations not working?

Ensure GSAP is installed (peer dependency)
Check browser console for errors
Verify you're not calling toast functions during SSR
Ensure you're using a modern browser

TypeScript errors?

Ensure @types/react is installed
Check TypeScript version (requires 4.1+)
Verify import paths are correct