JS Toast Notifier

JS Toast Notifier is a lightweight JavaScript library designed to provide a robust, flexible solution for displaying toast notifications. It offers a visually appealing, full Accessibility enabled , and customizable notification system, ideal for alerting users within web applications without being overly intrusive. With no dependencies and a straightforward setup, this library enables developers to quickly integrate notifications that enhance user interaction through positioning flexibility, droplet-style connectors, and pause-on-hover functionality. Below is a detailed description of the library's core features, configuration options, and API.

Basic Types

Positioning

Advanced Features

Themes & Styling

Custom Icons & Animations

Accessibility and Browser Support

JS Toast Notifier is designed with accessibility in mind. It adheres to WCAG 2.1 standards, including ARIA labels for screen readers, support for keyboard navigation, and respect for user preferences such as reduced motion. This cross-browser library is compatible with the latest versions of Chrome, Firefox, Safari, Edge, and Opera.

Custom Themes and CSS Customization

JS Toast Notifier supports custom themes and offers CSS class selectors for additional styling. For example, users can define custom colors, sizes, or animations that better align with their application's brand and style guidelines.

Key Features

Installation

npm install js-toast-notifier

Direct Usage via CDN

You can include JS Toast Notifier directly in your HTML using CDN links:

<!-- Add CSS in head -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/js-toast-notifier/dist/index.css">

<!-- Add JavaScript before closing body tag -->
<script src="https://cdn.jsdelivr.net/npm/js-toast-notifier/dist/index.umd.js"></script>

<script>
  // You can use it directly
  const toast = new ToastNotifier();
  
  // Or access via namespace if needed
  const toast2 = new ToastNotifier();
  
  toast.success('It works!');
</script>

Alternative CDN (unpkg)

<link rel="stylesheet" href="https://unpkg.com/js-toast-notifier/dist/index.css">
<script src="https://unpkg.com/js-toast-notifier/dist/index.umd.js"></script>
Check Examples

Basic Usage


import {ToastNotifier} from 'js-toast-notifier';

//import styling: you can ignore this if you want to customize it completly
import "js-toast-notifier/dist/toast.css"

// Initialize with default options
const toast = new ToastNotifier();

// Show a basic toast
toast.show('Hello, World!');

// Show different types of toasts
toast.success('Operation completed!');
toast.error('Something went wrong!');
toast.info('Here is some information.');
toast.warning('Please be careful!');

Configuration Options

Global Configuration

When initializing the toast instance, you can set default options for all notifications:


const toast = new ToastNotifier({
  position: 'top-right',      // Default position
  timeout: 5000,             // Default timeout in milliseconds
  theme: 'light',           // Default theme
  showCloseButton: true,    // Show close button
  pauseOnHover: true,       // Pause timer on hover
  showProgress: true,       // Show progress bar
  progressHeight: '4px',    // Progress bar height
  progressColor: '#fff',    // Progress bar color
  customClass: 'classname', // Add class on the Toast
  anchor: document.queryselector('.anchorelement'), // Anchor element
  progressBackground: 'rgba(255, 255, 255, 0.2)', // Progress background
  customContainerClass: 'class1 class2', // Add custom classes on container
  preferredAnchorPosition: 'top' // Preferred position for anchored toasts
});

toastOpened and Toast Closed Event

listen to these events to handle thing before or after toast

  
    let newtoast = toast.show('notification has been triggered')
    document.addEventListener('toastClosed', ()=>{
    })
    document.addEventListener('toastClosed', ()=>{
    })

    //OR

    newtoast.addEventListener('toastClosed', ()=>{
    })

Individual Toast Configuration

Each toast can override the global configuration:


// Custom themed toast
toast.show('Custom theme!', {
  theme: { backgroundColor: '#1a1a1a', textColor: '#ffffff' },
  customClass: 'my-custom-toast'
});

// Anchored toast with preferred bottom position
toast.show('Anchored below the button!', {
  anchor: document.getElementById('my-button'),
  preferredAnchorPosition: 'bottom'
});

// Toast with custom progress bar
toast.show('Custom progress!', {
  progressHeight: '6px',
  progressColor: '#00ff00',
  progressBackground: 'rgba(0, 0, 0, 0.3)',
  pauseOnHover: true
});

// Infinite toast (no timeout)
toast.show('Will not auto-close', { timeout: 0, showProgress: false });

API Reference

Constructor Options

Option Type Default Possible Values Description
position string 'top-right' 'top-center', 'bottom-center', 'left', 'right', 'top-left', 'top-right', 'bottom-left', 'bottom-right' Toast position
timeout number 5000 Any positive integer, 0 (for no auto-close) Auto-close duration in milliseconds
theme string | object 'light' 'light', 'dark', { backgroundColor: string, textColor: string, iconColor?: string } Theme name or custom theme object
showCloseButton boolean true true, false Show/hide close button
pauseOnHover boolean true true, false Pause timer on hover
Type string default success, error, warning, info, default, neutral, successLight, errorLight, infoLight, warningLight, highContrast, positive, negative, accentBlue, accentPink, accentPurple, accentTeal Define color Scheme
showProgress boolean true true, false Show/hide progress bar
progressHeight string '4px' Any valid CSS height value (e.g., '4px', '2em') Progress bar height
progressColor string - Any valid CSS color value (e.g., '#fff', 'rgba(0, 0, 0, 0.5)') Progress bar color
progressBackground string - Any valid CSS color value (e.g., '#eee', 'rgba(255, 255, 255, 0.2)') Progress bar background color
customClass string - Any valid CSS class Could be used for themes or tracking
preferredAnchorPosition string 'top' 'top', 'bottom' Preferred position for anchored toasts

Anchored Toast and Concurrency Example


// Attach a toast to the element with ID 'my-button' 
// and prefer anchoring below it:
const anchorElement = document.getElementById('my-button');
toast.show('Anchored below the button!', {
  anchor: anchorElement,
  preferredAnchorPosition: 'bottom'
});

// Limit concurrent toasts to 3:
const limitedToast = new ToastNotifier({ maxConcurrentToasts: 3 });
limitedToast.success('Only 3 toasts allowed at a time.');

Methods

show(message, options?)

Shows a toast notification with optional configuration.


toast.show('Message', {
  type: 'default',
  timeout: 3000
});


success(message, options?)

Shows a success toast.

toast.success('Operation completed!', { timeout: 3000 });

error(message, options?)

Shows an error toast.

toast.error('Failed to save!', { timeout: 0 });

info(message, options?)

Shows an info toast.

toast.info('New updates available');

warning(message, options?)

Shows a warning toast.

toast.warning('Low disk space');

Destroy

Remove All Toasts at once

toast.destroy();

Custom Themes

Create custom themes by providing a theme object:


const toast = new ToastNotifier({
  theme: {
    backgroundColor: '#1a1a1a',
    textColor: '#ffffff',
    iconColor: '#00ff00'
  }
});

CSS Customization

The package provides CSS classes for custom styling:


.toast {
  /* Custom styles */
}
.toast-progress {
  --progress-height: 6px;
  --progress-color: #00ff00;
  --progress-background: rgba(0, 0, 0, 0.2);
}
.toast:hover {
  transform: scale(1.02);
}

Accessibility

Accessibility Features

Screen Reader Behavior


// Success notifications are announced politely
toast.success('Operation completed!');

// Error notifications are announced immediately
toast.error('Connection failed!', {
  // Override ARIA attributes
  role: 'alert',
  'aria-live': 'assertive'
});

Browser Support

License

MIT

Visit My Profile