NotificationManager - Toast Notification System

This document describes NotificationManager, a toast notification system for the Now.js Framework that supports various message types with animations and automatic management.

📋 Table of Contents

1. Overview
2. Installation and Import
3. Getting Started
4. Notification Types
5. Configuration
6. Usage Examples
7. API Reference
8. Best Practices
9. Common Issues

Overview

NotificationManager is a toast notification system designed to display temporary messages to users without interrupting their workflow. It supports multiple notification types, animations, and automatic management.

Key Features

• ✅ Multiple Types: Supports success, error, warning, info, and loading
• ✅ Auto-dismiss: Automatically closes after a specified duration
• ✅ Smart Replacement: Automatically replaces notifications of the same type
• ✅ Animation: Supports various animation styles
• ✅ Adjustable Position: Can be positioned in 4 corners of the screen
• ✅ Progress Bar: Shows progress bar for auto-dismiss
• ✅ Queue System: Manages multiple concurrent notifications
• ✅ Accessibility: Supports ARIA attributes for screen readers
• ✅ RTL Support: Supports right-to-left languages

When to Use NotificationManager

✅ Recommended when:

• Need to notify users of action results
• Want to display temporary messages without interrupting workflow
• Need notifications with beautiful animations
• Need a system that handles multiple notifications

❌ Consider alternatives when:

• Need a dialog requiring user confirmation (use DialogManager instead)
• Need to display permanent messages on the page (use FormError instead)

Installation and Import

NotificationManager is loaded with the Now.js Framework and is immediately available through the window object:

// No import needed - ready to use
console.log(window.NotificationManager); // NotificationManager object

Getting Started

Basic Setup

// Initialize NotificationManager (done automatically by Now.js)
await NotificationManager.init({
  position: 'top-right',
  duration: 3000,
  maxVisible: 5,
  animation: true
});

console.log('NotificationManager is ready!');

Basic Usage Example

// Show success message
NotificationManager.success('Data saved successfully!');

// Show error message
NotificationManager.error('An error occurred. Please try again');

// Show warning
NotificationManager.warning('You have unsaved changes');

// Show info
NotificationManager.info('You have 3 new messages');

Notification Types

1. Success ✅

Used to notify successful operations

NotificationManager.success('Registration successful!');

// With additional options
NotificationManager.success('File uploaded successfully', {
  duration: 5000,
  progressBar: true
});

Properties:

• Duration: 3000ms (3 seconds) - auto-dismiss
• Icon: ✓ (valid)
• Color: Green

2. Error ❌

Used to notify errors that users need to be aware of

NotificationManager.error('Unable to save data');

// With additional options
NotificationManager.error('Connection lost', {
  duration: 8000  // Show longer, 8 seconds
});

Properties:

• Duration: 8000ms (8 seconds) - more time to read
• Icon: ⊗ (ban)
• Color: Red

Reason: Error messages require more time to read and understand, so they display longer than other types.

3. Warning ⚠️

Used to warn users about things they should be careful about

NotificationManager.warning('Your password will expire in 7 days');

// With additional options
NotificationManager.warning('Storage space is low', {
  duration: 8000
});

Properties:

• Duration: 8000ms (8 seconds) - more time to read
• Icon: ⚠ (warning)
• Color: Orange/Yellow

Reason: Warning messages are important information users should be aware of and may need time to read and make decisions.

4. Info ℹ️

Used for general non-critical information

NotificationManager.info('System maintenance on Sunday');

// With additional options
NotificationManager.info('New version available', {
  duration: 5000
});

Properties:

• Duration: 3000ms (3 seconds) - auto-dismiss
• Icon: ℹ (info)
• Color: Blue

5. Loading ⏳

Used to show working status, must be closed with code

// Show loading
const loadingId = NotificationManager.loading('Uploading file...');

// Do something
await uploadFile();

// Close loading
NotificationManager.dismiss(loadingId);

// Or show result
NotificationManager.success('Upload complete!');

Properties:

• Duration: 0 (doesn't auto-dismiss)
• Icon: ⟳ (loader)
• Dismissible: false (can't be manually closed)

Configuration

Global Configuration

NotificationManager.init({
  // Display position
  position: 'top-right',  // top-right, top-left, bottom-right, bottom-left

  // Default display duration (milliseconds)
  duration: 3000,

  // Maximum number to display simultaneously
  maxVisible: 5,

  // Enable/disable animation
  animation: true,

  // Manually dismissible
  dismissible: true,

  // Show close button
  closeButton: true,

  // Show icon
  icons: true,

  // Show progress bar
  progressBar: false,

  // Pause on hover
  pauseOnHover: false,

  // RTL support
  rtl: false,

  // ARIA support
  aria: true
});

Per-Instance Configuration

// Set duration for specific instance
NotificationManager.success('Saved successfully', {
  duration: 5000  // Show for 5 seconds
});

// Disable progress bar
NotificationManager.error('An error occurred', {
  progressBar: false
});

// Make non-dismissible
NotificationManager.warning('Please wait', {
  dismissible: false,
  duration: 0  // Don't auto-dismiss
});

Usage Examples

Example 1: Form Submission

// When submitting form
document.getElementById('myForm').addEventListener('submit', async (e) => {
  e.preventDefault();

  // Show loading
  const loadingId = NotificationManager.loading('Saving data...');

  try {
    // Send data
    const response = await fetch('/api/save', {
      method: 'POST',
      body: new FormData(e.target)
    });

    // Close loading
    NotificationManager.dismiss(loadingId);

    if (response.ok) {
      // Show success
      NotificationManager.success('Data saved successfully!');
    } else {
      // Show error
      NotificationManager.error('Unable to save data');
    }
  } catch (error) {
    // Close loading
    NotificationManager.dismiss(loadingId);

    // Show error
    NotificationManager.error('Error: ' + error.message);
  }
});

Example 2: File Upload

async function uploadFile(file) {
  // Show loading with progress bar
  const loadingId = NotificationManager.loading('Uploading...', {
    progressBar: true
  });

  try {
    const formData = new FormData();
    formData.append('file', file);

    const response = await fetch('/api/upload', {
      method: 'POST',
      body: formData
    });

    // Close loading
    NotificationManager.dismiss(loadingId);

    if (response.ok) {
      NotificationManager.success('File uploaded successfully!');
    } else {
      NotificationManager.error('Upload failed');
    }
  } catch (error) {
    NotificationManager.dismiss(loadingId);
    NotificationManager.error('Error: ' + error.message);
  }
}

Example 3: Multiple Notifications

// Show multiple notifications simultaneously
NotificationManager.info('Starting processing...');

setTimeout(() => {
  NotificationManager.info('Processing data...');
}, 1000);

setTimeout(() => {
  NotificationManager.success('Processing complete!');
}, 3000);

Note: The system automatically replaces notifications of the same type to prevent redundancy.

Example 4: Using with FormManager

// Listen to FormManager events
document.addEventListener('form:submitted', (e) => {
  const { response } = e.detail;

  if (response.success) {
    NotificationManager.success(response.message || 'Saved successfully!');
  } else {
    NotificationManager.error(response.message || 'An error occurred');
  }
});

document.addEventListener('form:error', (e) => {
  NotificationManager.error('Please check the form data');
});

API Reference

Methods

init(options)

Initialize NotificationManager

await NotificationManager.init({
  position: 'top-right',
  duration: 3000,
  maxVisible: 5
});

Parameters:

• options (Object) - Configuration (see Configuration)

Returns: Promise<NotificationManager>

setPosition(position)

Change notification display position

NotificationManager.setPosition('top-left');

Parameters:

• position (String) - Position: 'top-right', 'top-left', 'bottom-right', 'bottom-left'

Returns: void

show(options)

Show custom notification

NotificationManager.show({
  type: 'success',
  message: 'Your message',
  duration: 5000,
  icon: 'custom-icon'
});

Parameters:

• options (Object|String) - Options or message
  • type (String) - Type: 'success', 'error', 'warning', 'info', 'loading'
  • message (String) - Message to display
  • duration (Number) - Display duration (milliseconds), 0 = no auto-dismiss
  • icon (String) - Icon class name
  • dismissible (Boolean) - Manually dismissible
  • progressBar (Boolean) - Show progress bar

Returns: String - Notification ID

success(message, options)

Show success notification

NotificationManager.success('Saved successfully!');

Parameters:

• message (String) - Message
• options (Object) - Additional options (optional)

Returns: String - Notification ID

Default Properties:

• Duration: 3000ms
• Icon: 'valid'
• Type: 'success'

error(message, options)

Show error notification

NotificationManager.error('An error occurred!');

Parameters:

• message (String) - Message
• options (Object) - Additional options (optional)

Returns: String - Notification ID

Default Properties:

• Duration: 8000ms (more time to read)
• Icon: 'ban'
• Type: 'error'

warning(message, options)

Show warning notification

NotificationManager.warning('Please check your data');

Parameters:

• message (String) - Message
• options (Object) - Additional options (optional)

Returns: String - Notification ID

Default Properties:

• Duration: 8000ms (more time to read)
• Icon: 'warning'
• Type: 'warning'

info(message, options)

Show info notification

NotificationManager.info('You have new messages');

Parameters:

• message (String) - Message
• options (Object) - Additional options (optional)

Returns: String - Notification ID

Default Properties:

• Duration: 3000ms
• Icon: 'info'
• Type: 'info'

loading(message, options)

Show loading notification

const id = NotificationManager.loading('Loading...');
// Do something
NotificationManager.dismiss(id);

Parameters:

• message (String) - Message
• options (Object) - Additional options (optional)

Returns: String - Notification ID

Default Properties:

• Duration: 0 (no auto-dismiss)
• Icon: 'loader'
• Type: 'loading'
• Dismissible: false

dismiss(id)

Close specified notification

const id = NotificationManager.success('Success!');
// Close immediately
NotificationManager.dismiss(id);

Parameters:

• id (String) - ID of notification to close

Returns: void

clear()

Close all notifications

NotificationManager.clear();

Returns: void

Best Practices

1. Choose Appropriate Type

// ✅ Good - Use appropriate type for situation
NotificationManager.success('Saved successfully');
NotificationManager.error('Cannot connect');
NotificationManager.warning('Password will expire');
NotificationManager.info('New messages');

// ❌ Bad - Using inappropriate type
NotificationManager.success('An error occurred'); // Should use error
NotificationManager.error('Saved successfully'); // Should use success

2. Concise and Clear Messages

// ✅ Good - Short and concise message
NotificationManager.success('Saved successfully!');
NotificationManager.error('Cannot save');

// ❌ Bad - Message too long
NotificationManager.success('The system has successfully saved your data and will redirect you to the next page');

3. Always Close Loading

// ✅ Good - Close loading in all cases
const loadingId = NotificationManager.loading('Loading...');
try {
  await doSomething();
  NotificationManager.dismiss(loadingId);
  NotificationManager.success('Success!');
} catch (error) {
  NotificationManager.dismiss(loadingId);
  NotificationManager.error('Error!');
}

// ❌ Bad - Forgot to close loading
const loadingId = NotificationManager.loading('Loading...');
await doSomething();
// Forgot to close loading!

4. Use Appropriate Duration

// ✅ Good - Short message, short duration
NotificationManager.success('Saved', { duration: 2000 });

// ✅ Good - Long message, long duration
NotificationManager.error('Cannot save. Please check your internet connection', {
  duration: 8000
});

// ❌ Bad - Long message but short duration
NotificationManager.error('Very long message...', { duration: 1000 }); // Can't read in time

5. Avoid Redundancy

// ✅ Good - System automatically replaces notifications of same type
NotificationManager.error('Error 1');
NotificationManager.error('Error 2'); // Will replace first message

// ✅ Good - Use clear() before showing new
NotificationManager.clear();
NotificationManager.success('Starting fresh');

Common Issues

1. Notification Not Showing

Cause: Haven't called init()

// ❌ Bad
NotificationManager.success('Success'); // May not show

// ✅ Good
await NotificationManager.init();
NotificationManager.success('Success');

2. Loading Won't Dismiss

Cause: Forgot to call dismiss()

// ✅ Good - Use try-finally
const loadingId = NotificationManager.loading('Loading...');
try {
  await doSomething();
} finally {
  NotificationManager.dismiss(loadingId); // Close in all cases
}

3. Too Many Notifications

Solution: Adjust maxVisible or use clear()

// Set maximum number
NotificationManager.init({
  maxVisible: 3
});

// Or clear before showing new
NotificationManager.clear();
NotificationManager.success('New message');

4. Message Too Long

Solution: Use short concise message or increase duration

// ✅ Good - Short message
NotificationManager.error('Save failed');

// ✅ Good - Long message + long duration
NotificationManager.error('Cannot save. Please check your data', {
  duration: 10000
});

Duration Guidelines

Smart Replacement Feature

NotificationManager automatically replaces notifications of the same type to prevent redundancy:

// Show first error
NotificationManager.error('Error 1');

// Show second error - will automatically replace first error
NotificationManager.error('Error 2');

// Result: Will only see "Error 2"

Benefits:

• Prevents notification overflow
• Users always see the latest message
• Doesn't interrupt workflow

Exception: Loading notifications won't be replaced because there may be multiple loadings simultaneously.

Related Documentation

• FormManager - Form management system
• FormError - Form error display system
• DialogManager - Dialog and modal system

License

Now.js Framework is released under the MIT License

Latest Updates

• Version: 2.0.0
• Last Updated: 2025-11-28
• Changes:
  • Adjusted error and warning duration to 8000ms
  • Added Smart Replacement feature
  • Improved animation and UX