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.

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
Check Examples

Basic Usage


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

// 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
  progressBackground: 'rgba(255, 255, 255, 0.2)' // Progress background
});

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 custom position
toast.show('Anchored to button!', {
  anchor: document.getElementById('my-button'),
  position: 'top',
  timeout: 3000
});

// 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', 'bottom', '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
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

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

Browser Support

License

MIT

Basic Types

Positioning

Advanced Features

Themes & Styling