ng-angular-popup

A modern, lightweight, and highly customizable toast notification library for Angular 18+ applications with full support for signals, zoneless mode, and standalone components.

✨ What's New in v2.0.0

• 🎯 Global Configuration via DI: Configure all toast settings globally through provideNgToast()
• ⚡ Pure CSS Animations: No deprecated Angular animation APIs - works perfectly in zoneless mode
• 🎪 Bouncy Spring Animations: Beautiful enter and exit animations with spring physics
• 🎨 Optional Icons: Show/hide icons per toast or globally
• 📐 Optimized Sizing: Compact, professional design following modern web standards
• 📱 Better Mobile Support: Enhanced responsive design for all devices
• 🚀 Angular 20 Ready: Full support for Angular 18, 19, and 20

Features

• 🚀 Angular 18-20 Support: Fully compatible with latest Angular versions
• ⚡ Signals-based: Uses Angular's signals API for reactive state management
• 🎯 Zoneless Compatible: Works perfectly without zone.js for maximum performance
• 🧩 Standalone Components: Fully supports Angular's standalone component architecture
• 🔄 OnPush Change Detection: Optimized performance
• 🎨 Global Configuration: Configure once, use everywhere via DI
• 📱 Fully Responsive: Mobile, tablet, and desktop optimized
• 🎪 Smooth Animations: Bouncy spring animations for enter/exit
• 🎯 6 Positions: top/bottom × left/center/right
• 🌈 6 Toast Types: Success, Error, Warning, Info, Primary, Secondary
• ⏱️ Progress Bars: Visual countdown indication
• 🖐️ Dismissible: Manual dismiss with animation
• 🖼️ Optional Icons: Show/hide icons per toast
• 🆕 Modern Syntax: Uses @for and @if control flow

Installation

npm install ng-angular-popup

Quick Start

1. Basic Setup (Zoneless Mode - Recommended)

// app.config.ts
import { ApplicationConfig, provideZonelessChangeDetection } from '@angular/core';
import { provideNgToast } from 'ng-angular-popup';

export const appConfig: ApplicationConfig = {
  providers: [
    provideZonelessChangeDetection(),
    provideNgToast(),
  ]
};

2. Global Configuration (New in v2.0.0!)

Configure toast behavior globally:

// app.config.ts
import { provideNgToast } from 'ng-angular-popup';

export const appConfig: ApplicationConfig = {
  providers: [
    provideZonelessChangeDetection(),
    provideNgToast({
      duration: 5000,              // Default 5 seconds
      position: 'top-right',       // Default position
      maxToasts: 3,                // Max 3 toasts at once
      width: 400,                  // Toast width in pixels
      showProgress: true,          // Show progress bar
      dismissible: true,           // Allow manual dismiss
      showIcon: true,              // Show icons
      enableAnimations: true       // Enable animations
    }),
  ]
};

3. Add Component to Template

import { Component } from '@angular/core';
import { NgToastComponent, NgToastService, TOAST_POSITIONS, ToastPosition } from 'ng-angular-popup';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [NgToastComponent], // Import the component
  template: `
    <h1>My App</h1>
    <button (click)="showToast()">Show Toast</button>
    
    <!-- Add toast component (uses global config) -->
    <ng-toast></ng-toast>
  `
})
export class AppComponent {
  constructor(private toast: NgToastService) {}
  
  showToast() {
    // Uses global configuration
    this.toast.success('Operation successful!', 'Success');
  }
}

NgModule (Legacy Support)

1. Import NgToastModule in your app.module.ts:

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { BrowserAnimationsModule } from '@angular/platform-browser/animations';
import { NgToastModule } from 'ng-angular-popup';

@NgModule({
  imports: [
    BrowserModule,
    BrowserAnimationsModule, // Required for animations
    NgToastModule
    // ...
  ]
})
export class AppModule { }

2. Add the toast component to your app.component.html:

<ng-toast [position]="TOAST_POSITIONS.TOP_RIGHT" [width]="350"></ng-toast>

3. Inject and use the service in your components:

import { NgToastService, TOAST_POSITIONS } from 'ng-angular-popup';

@Component({
  // ...
})
export class YourComponent {
  TOAST_POSITIONS = TOAST_POSITIONS; // Make positions available in template
  
  constructor(private toast: NgToastService) {}

  showSuccess() {
    this.toast.success('Success Message', 'Title', 3000);
  }

  showError() {
    this.toast.danger('Error Message', 'Error', 3000);
  }

  showInfo() {
    this.toast.info('Info Message', 'Information', 3000);
  }

  showWarning() {
    this.toast.warning('Warning Message', 'Warning', 3000);
  }
}

API Reference

Global Configuration Options

Configure via provideNgToast():

| Option | Type | Default | Description | |--------|------|---------|-------------| | duration | number | 3000 | Default duration in milliseconds | | position | ToastPosition | 'bottom-right' | Default toast position | | maxToasts | number | 5 | Maximum toasts to display | | width | number | 350 | Toast container width (px) | | showProgress | boolean | true | Show progress bar by default | | dismissible | boolean | true | Allow manual dismiss by default | | showIcon | boolean | true | Show icons by default | | enableAnimations | boolean | true | Enable animations |

Toast Service Methods

All methods now support optional parameters that override global config:

| Method | Signature | Description | |--------|-----------|-------------| | success() | (message, title?, duration?, showProgress?, dismissible?, showIcon?) | Success toast | | danger() | (message, title?, duration?, showProgress?, dismissible?, showIcon?) | Error toast | | info() | (message, title?, duration?, showProgress?, dismissible?, showIcon?) | Info toast | | warning() | (message, title?, duration?, showProgress?, dismissible?, showIcon?) | Warning toast | | primary() | (message, title?, duration?, showProgress?, dismissible?, showIcon?) | Primary toast | | secondary() | (message, title?, duration?, showProgress?, dismissible?, showIcon?) | Secondary toast | | removeToast() | (messageId: number) | Remove specific toast | | clearAll() | () | Remove all toasts | | setMaxToasts() | (max: number) | Set max toasts | | getConfig() | () | Get current config |

Usage Examples

// Use global config
this.toast.success('Saved!');

// Override specific options
this.toast.success('Saved!', 'Success', 5000, true, true, false); // No icon

// Without icon globally
provideNgToast({ showIcon: false });

// Persistent toast (no auto-dismiss)
this.toast.info('Important info', 'Notice', 0); // duration: 0

// Custom position per component
<ng-toast [position]="'top-right'" [width]="400"></ng-toast>

Accessibility Features

• High Contrast Colors: All toast types use WCAG 2.1 AA compliant color combinations
• Keyboard Navigation: Dismissible toasts can be closed using keyboard
• Screen Reader Support: Proper ARIA attributes for screen readers
• Focus Management: Proper focus handling for interactive elements
• Readable Text: Optimized font sizes and weights for readability

TOAST_POSITIONS

// Available as a const object
const TOAST_POSITIONS = {
  TOP_LEFT: 'toaster-top-left',
  TOP_CENTER: 'toaster-top-center',
  TOP_RIGHT: 'toaster-top-right',
  BOTTOM_LEFT: 'toaster-bottom-left',
  BOTTOM_CENTER: 'toaster-bottom-center',
  BOTTOM_RIGHT: 'toaster-bottom-right'
} as const;

// Type for toast positions
type ToastPosition = typeof TOAST_POSITIONS[keyof typeof TOAST_POSITIONS];

Styling and Customization

Default Accessible Colors

The library uses a carefully selected color palette that meets WCAG 2.1 AA accessibility standards with proper contrast ratios:

| Toast Type | Border Color | Background Color | Text Color | |------------|--------------|------------------|------------| | Primary | #4338ca (Indigo) | #eef2ff (Indigo 50) | #111827 (Dark) | | Secondary | #374151 (Slate) | #f1f5f9 (Slate 100) | #111827 (Dark) | | Success | #047857 (Emerald) | #ecfdf5 (Emerald 50) | #111827 (Dark) | | Info | #0369a1 (Cyan) | #ecfeff (Cyan 50) | #111827 (Dark) | | Warning | #b45309 (Amber) | #fffbeb (Amber 50) | #111827 (Dark) | | Danger | #b91c1c (Red) | #fef2f2 (Red 50) | #111827 (Dark) |

Custom Styling

You can customize the toast appearance by overriding the CSS classes. Add your custom styles in your global styles file:

// Example customization
.toast-message {
  // Modify base toast styles
  border-radius: 12px;
  box-shadow: 0 8px 16px rgba(0, 0, 0, 0.1);
  
  // Customize specific toast types
  &.toast-success {
    border-left: 6px solid #047857;
    background-color: #ecfdf5;
  }

  &.toast-danger {
    border-left: 6px solid #b91c1c;
    background-color: #fef2f2;
  }

  &.toast-info {
    border-left: 6px solid #0369a1;
    background-color: #ecfeff;
  }
  
  &.toast-warning {
    border-left: 6px solid #b45309;
    background-color: #fffbeb;
  }
  
  // Customize toast content
  .msg-title {
    font-size: 1rem;
    font-weight: 600;
  }
  
  .msg-summary {
    font-size: 0.9375rem;
  }
  
  // Customize progress bar
  .toast-progress {
    height: 4px;
    opacity: 0.3;
  }
}

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Angular Version Compatibility

| Library Version | Angular Version | Features | |----------------|------------------|----------| | 2.0.0+ | Angular 18-20 | Signals, Zoneless, Global Config, Pure CSS Animations | | 1.x.x | Angular 12-17 | Basic features |

Migration Guide (v1 → v2)

Breaking Changes

1. Minimum Angular Version: Now requires Angular 18+
2. Removed Deprecated APIs: No longer uses deprecated Angular animation APIs
3. Peer Dependencies: Removed @angular/animations requirement

Migration Steps

// Before (v1)
import { provideAnimations } from '@angular/platform-browser/animations';
provideAnimations(), // No longer needed!
provideNgToast()

// After (v2) - Zoneless mode
provideZonelessChangeDetection(),
provideNgToast({
  // Optional global config
  duration: 5000,
  showIcon: true
})

New Features in v2

• ✅ Global configuration via DI
• ✅ Optional icons (show/hide per toast or globally)
• ✅ Pure CSS animations (no deprecated APIs)
• ✅ Bouncy spring animations
• ✅ Better mobile/tablet support
• ✅ Optimized sizing

Changelog

v2.0.0 (2025-01-04)

🎉 Major Release - Angular 18-20 Support

• ✨ NEW: Global configuration via provideNgToast(config)
• ✨ NEW: Optional icons with showIcon parameter
• ✨ NEW: Pure CSS animations (zoneless compatible)
• ✨ NEW: Bouncy spring enter/exit animations
• 📐 IMPROVED: Optimized sizing for modern web standards
• 📱 IMPROVED: Better responsive design for mobile/tablet
• ⚡ IMPROVED: Full zoneless mode support
• 🔧 CHANGED: Minimum Angular version is now 18
• 🗑️ REMOVED: Deprecated Angular animation APIs
• 🗑️ REMOVED: @angular/animations peer dependency

v1.0.0

• Initial release with Angular 12-17 support

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Sashikumar Yadav

• Email: [email protected]
• GitHub: @yshashi

Support

If you like this project, please consider giving it a ⭐️ on GitHub!