Package Exports

customizable-toast-notification
customizable-toast-notification/package.json

Readme

🍞 Customizable Toast Notifications

npm npm downloads

A lightweight, zero-dependency toast notification library for modern JavaScript applications. Built with production-grade reliability and comprehensive secret mechanisms.

✨ Key Features

🚫 Zero Dependencies - Pure JavaScript with no external requirements Lightweight and fast
🛡️ Production Ready - Reliable and scalable for production environments
🎨 Highly Customizable - Colors, positions, animations, progress bars
🌐 Framework Agnostic - Works with React, Vue, Angular, or vanilla JS
📱 Responsive - Works on all screen sizes and devices
⚡ CDN Ready - Easy integration via CDN or npm
🎨 Fully Customizable - Colors, positions, animations, and styling
♿ Accessible - ARIA live regions and keyboard navigation support
🔄 Smart Grouping - Duplicate notifications are automatically grouped with badges
⏸️ Pause on Hover - CTA toasts pause when user hovers or focuses
🎯 Call-to-Action - Built-in support for interactive buttons and links
📊 Queue Management - Maximum 3 visible toasts with intelligent queueing
🌈 Multiple Themes - Success, error, warning, and info styles
🔧 TypeScript Ready - TypeScript definitions included Full type support (coming soon)

📦 Installation

NPM/Yarn

npm install customizable-toast-notification

yarn add customizable-toast-notification

🚀 Quick Start

ES Modules

import { createToast, setDefaultColors, setDefaultMessages } from 'customizable-toast-notification';

// Simple usage
createToast({
message: "Hello World!",
type: "success",
duration: 3000
});

CDN/Browser (UMD Build) / Quick Try with jsDelivr

Global Variable Name: customizableToast

<!-- Always latest version -->
<script src="https://cdn.jsdelivr.net/npm/customizable-toast-notification/dist/index.umd.js"></script>

<!-- OR pin to a specific version (recommended for stability) -->
<script src="https://cdn.jsdelivr.net/npm/customizable-toast-notification@3.9.5/dist/index.umd.js"></script>

<script>
  // Access the global UMD export
  customizableToast.createToast({
    message: "Hello from jsDelivr! 🚀",
    backgroundColor: "black",
    textColor: "snow",
    position: "top-center",
    animationDuration: "3s",
    animationEasing: "ease",
    progressPosition: "top",
    cta: {
        autoClose: false,
        label: "Check Pkg!",
        href: "https://www.npmjs.com/package/customizable-toast-notification",
        variant: "link",
        target: "_blank"
    }
  });
</script>

📖 API Reference

`createToast(options)`

Creates and displays a toast notification.

Options

Parameter	Type	Default	Description
`message`	`string`	Based on `type`	Toast message content
`type`	`string`	`"info"`	`"info"`, `"success"`, `"error"`, `"warning"`
`duration`	`number`	`3000`	Auto-dismiss time in milliseconds
`position`	`string`	`"bottom-right"`	Toast position on screen
`backgroundColor`	`string`	Based on `type`	Custom background color
`textColor`	`string`	`"white"`	Custom text color
`showCloseButton`	`boolean`	`false`	Show close (×) button
`showProgressBar`	`boolean`	`false`	Show countdown progress bar
`animationDuration`	`string`	`"0.5s"`	CSS animation duration
`animationEasing`	`string`	`"ease"`	CSS animation easing function
`progressColor`	`string`	`rgba(255,255,255,0.3)`	Progress bar color
`progressHeight`	`string`	`"4px"`	Progress bar height
`progressPosition`	`string`	`"bottom"`	Progress bar position: `"top"` or `"bottom"`
`pauseOnHover`	`boolean`	`auto`	Pause timer on hover (auto: true for CTA toasts)
`cta`	`object`	`null`	Call-to-action configuration (see CTA)

Position Options

// Corner positions
- "top-left", "top-right", "bottom-left", "bottom-right"

// Edge positions
- "top-center", "bottom-center", "left-center", "right-center"

// Full width
- "top-full-width", "bottom-full-width"

// Center
- "center"

🎯 Call-to-Action (CTA)

Add interactive buttons or links to your toasts:

// Button CTA
createToast({
message: "File uploaded successfully!",
type: "success",
cta: {
label: "View File",
onClick: () => {
window.open('/files/latest');
},
autoClose: true // Close toast after click (default: true)
}
});

// Link CTA
createToast({
message: "New version available!",
cta: {
label: "Download",
href: "https://example.com/download",
variant: "link",
target: "_blank"
}
});

// Advanced CTA with async action
createToast({
message: "Ready to sync your data?",
cta: {
label: "Sync Now",
ariaLabel: "Start data synchronization",
autoClose: false,
onClick: async () => {
await performDataSync();
// Manually close if needed
}
}
});

CTA Options

Parameter	Type	Default	Description
`label`	`string`	`required`	Button/link text
`onClick`	`function`	`null`	Click handler (for buttons)
`href`	`string`	`null`	URL (for links)
`variant`	`string`	`"button"`	`"button"` or `"link"`
`target`	`string`	`null`	Link target (`"_blank"`, etc.)
`rel`	`string`	`auto`	Link relationship
`autoClose`	`boolean`	`true`	Close toast after CTA click
`ariaLabel`	`string`	`label`	Accessibility label

🎨 Examples

All Toast Types

`setDefaultColors(colors)`

Configure default colors for toast types.

setDefaultColors({
success: "#10b981",
error: "#ef4444",
warning: "#f59e0b",
info: "#3b82f6"
});

`setDefaultMessages(messages)`

Configure default messages for toast types.

setDefaultMessages({
success: "Operation completed successfully!",
error: "Something went wrong!",
warning: "Please check your input!",
info: "Here's some information!"
});

💡 Examples

Basic Toast Types

// Success
createToast({ type: "success", message: "Data saved!" });

// Error
createToast({ type: "error", message: "Save failed!" });

// Warning
createToast({ type: "warning", message: "Please confirm!" });

// Info
createToast({ type: "info", message: "New update available!" });

Advanced Customization

createToast({
message: "File uploading...",
type: "info",
duration: 5000,
position: "top-center",
showProgressBar: true,
showCloseButton: true,
backgroundColor: "#6366f1",
textColor: "white",
progressColor: "#e0e7ff",
progressPosition: "top",
animationDuration: "0.8s",
animationEasing: "ease-out"
});

### App-wide Configuration

// Set your brand colors once
setDefaultColors({
success: "#10b981", // Your brand green
error: "#ef4444", // Your brand red
warning: "#f59e0b", // Your brand yellow
info: "#3b82f6" // Your brand blue
});

// Set your app messages
setDefaultMessages({
success: "✅ Success! Changes saved.",
error: "❌ Error! Please try again.",
warning: "⚠️ Warning! Check your input.",
info: "💡 Info! Here's a tip."
});

// Now just use types throughout your app
createToast({ type: "success" }); // Uses your custom colors & messages

🔄 Advanced Features

Smart Grouping

Identical toasts (same type, message, and position) are automatically grouped:

Shows a single toast with a badge counter
Resets the dismiss timer when new duplicates arrive
Maximum of 3 toasts visible at once

Queue Management

Only 3 toasts are shown simultaneously
Additional toasts are queued automatically
Queue is processed as toasts are dismissed

Accessibility

ARIA live regions announce new toasts to screen readers
Keyboard navigation support (Tab, Enter, Escape)
High contrast badge design
Semantic HTML structure

🛡️ Reliability Features

Production-Grade System

**Rich toast → Basic toast → Emergency alert
Zero-Crash Guarantee: Comprehensive error handling prevents application crashes
Memory Management: Automatic cleanup prevents memory leaks
CDN Cache-Busting: Ensures fresh content delivery

Browser Compatibility

✅ Chrome
✅ Firefox
✅ Safari
✅ Edge
✅ Mobile browsers

📁 Bundle Information

Size: ~8KB minified, ~4KB gzipped
Dependencies: Zero
Formats: UMD, ES Modules
TypeScript: Definitions included (full coming soon)

🤝 Contributing

Exciting times ahead! Looking for sponsors and eager to explore new collaborations:) . Contributions are welcome! Please read our Contributing Guidelines for details.

Development Setup

git clone https://github.com/sammy-cool/customizable-toast-notification.git
cd customizable-toast-notification
npm install
npm run build

📄 License

This project is licensed under the Apache-2.0 License.

👨‍💻 Author

Priyanshu Patel

📧 Email: priyanshu.alt191@gmail.com
🐙 GitHub: @sammy-cool

💖 Support

If this library helped your project, please consider:

⭐ Star this repository to show your support!

💌 Share feedback at priyanshu.alt191@gmail.com

☕ Buy me a coffee if you'd like to support development:

🌐 PayPal: paypal.me/priyanshupatel1
💳 UPI: eureka91@upi

📱 Support via QR Code

Support QR

Thank you for your support! 🙏

Made with ❤️ for the JavaScript community