Lightweight Toast & Growl Notifications Inspired by macOS – Toastify

Toastify is a vanilla JavaScript library that creates elegant toast- and growl-like notifications inspired by macOS.

It provides built-in theme support for light and dark modes, responsive animations that adapt to mobile and desktop viewports, and complete TypeScript definitions for type-safe development.

Features:

• Theme System: Built-in light and dark themes with automatic system preference detection.
• Responsive Animations: Mobile devices show single notifications with fade effects, while desktop displays stack multiple toasts with smooth slide transitions.
• Timing Controls: Control over display intervals, fade-out delays, and sequential timing between multiple notifications.
• Accessible: Proper ARIA attributes for screen readers, including role=”alert” and aria-live regions.

See It In Action:

Use Cases:

• Form Validation Feedback: Display success or error messages after form submissions.
• Background Process Updates: Notify users when asynchronous operations complete.
• System Status Notifications: Alert users to connectivity changes, session timeouts, or application state updates.
• Progressive Web App Events: Communicate service worker updates, offline mode transitions, or cache refresh notifications.

How To Use It:

1. Install the Toastify package with NPM.

# NPM
$ npm install @zzev/toastify

2. The library provides two classes: Theme for styling and Core for notification logic. You can import them using either default or named exports.

// Named imports (recommended approach)
import { Theme, Core } from '@zzev/toastify';

// Initialize the theme system
// Pass 'light', 'dark', or null for automatic detection
const theme = new Theme('dark');

// Create the core notification instance
const toast = new Core();

// Configure and initialize the toast system
await toast.init({
  // Inject the theme's CSS styles
  styles: theme.styles,
  
  // Define your notification messages
  messages: [
    {
      img: 'https://placehold.co/64x64',      // Icon or avatar image
      title: 'Welcome Back',                   // Notification heading
      time: 'now',                             // Timestamp text
      text: 'Your session has been restored'   // Message body
    }
  ],
  
  // Control timing behavior
  delays: {
    startAfterMs: 1000,        // Wait 1 second before showing first toast
    displayIntervalMs: 2000,   // Show next toast after 2 seconds
    fadeOutMs: 5000            // Remove toast after 5 seconds (0 = never)
  }
});

// Start displaying the notifications
toast.run();

3. The Theme class handles all styling and color schemes. It accepts two parameters during initialization.

// Automatic theme (follows system preferences)
const autoTheme = new Theme(null);

// Force light theme
const lightTheme = new Theme('light');

// Force dark theme with custom mobile breakpoint
// Default mobile breakpoint is 768px
const darkTheme = new Theme('dark', 640);

// Access the generated CSS
const cssStyles = darkTheme.styles;

// Change theme after initialization
darkTheme.setTheme('light');

4. The library queues multiple messages and displays them sequentially based on your timing configuration.

On desktop, each new toast pushes previous notifications down the screen with a slide animation. On mobile, only the current toast displays. Previous toasts fade out before the next one appears.

const messages = [
  {
    img: 'https://placehold.co/64x64/00ff00/white',
    title: 'Upload Complete',
    time: 'now',
    text: 'Your file has been processed successfully'
  },
  {
    img: 'https://placehold.co/64x64/0099ff/white',
    title: 'New Comment',
    time: '2m ago',
    text: 'Sarah replied to your thread'
  },
  {
    img: 'https://placehold.co/64x64/ffaa00/white',
    title: 'Storage Warning',
    time: '5m ago',
    text: 'You have used 90% of available space'
  }
];

await toast.init({
  styles: theme.styles,
  messages,
  delays: {
    startAfterMs: 500,       // Begin quickly after page load
    displayIntervalMs: 3000, // 3 seconds between each toast
    fadeOutMs: 0             // Keep toasts visible indefinitely
  }
});

toast.run();

5. All configuration options.

• styles (string): The CSS stylesheet generated by Theme.styles. This injects all necessary styles for toast appearance, animations, and responsive behavior.
• messages (Array): An array of notification objects. Each object requires four properties: img (image URL), title (heading text), time (timestamp string), and text (message content).
• delays.startAfterMs (number): Milliseconds to wait before displaying the first toast. Default is 1000ms. Set to 0 for immediate display.
• delays.displayIntervalMs (number): Milliseconds between each sequential toast appearance. Default is 2000ms. This controls the pacing of multiple notifications.
• delays.fadeOutMs (number): Milliseconds before toasts fade out and remove themselves. Default is 5000ms. Set to 0 to prevent automatic removal. The toast remains visible until manually stopped.

6. API methods.

// Initialize the notification system with configuration
// This must be called before run()
await toast.init({
  styles: theme.styles,
  messages: messageArray,
  delays: timingConfig
});

// Start the notification sequence
// Toasts will appear based on your timing configuration
toast.run();

// Stop all current toasts and clear the queue
// Removes visible toasts immediately
toast.stop();

// Complete cleanup - removes toasts, styles, and resets state
// Use this when permanently removing the notification system
toast.destroy();

// Update configuration and restart
// Equivalent to destroy() followed by init() and run()
await toast.update({
  styles: newTheme.styles,
  messages: updatedMessages,
  delays: newTimingConfig
});

Alternative Libraries:

• 10 Best Toast Notification JavaScript Libraries
• 10 Best React Toast Components To Enhance Notification Experience

FAQs:

Q: Can I display toasts immediately without the initial delay?
A: Set startAfterMs to 0 in your delays configuration. The first toast will appear as soon as you call run().

Q: How do I prevent toasts from disappearing automatically?
A: Set fadeOutMs to 0 in your delays configuration. Toasts will remain visible until you explicitly call stop() or destroy().

Q: The toasts appear in the wrong position on my page. How do I fix this?
A: The library uses fixed positioning with right: 16px and top: 16px by default. If you need different positioning, override the .toastify-toast class in your own CSS after the library styles load. You can use if necessary, or increase your CSS specificity.

Q: Can I change the theme after initialization without restarting the notifications?
A: You need to reinitialize the toast system. Call destroy() to remove the old styles, update your theme instance with setTheme(), then call init() and run() again. For a single operation, use the update() method with your new configuration.

Q: Why do my toasts appear stacked on mobile devices when I have multiple messages?
A: Check your viewport width. The library considers devices under 768px (by default) as mobile.

The post Lightweight Toast & Growl Notifications Inspired by macOS – Toastify appeared first on CSS Script.