ng-angular-popup
Version:
A modern, lightweight, and customizable toast notification library for Angular 18-22 with signals, zoneless support, and standalone components
406 lines (310 loc) • 12.6 kB
Markdown
# ng-angular-popup
[](https://badge.fury.io/js/ng-angular-popup)
[](https://opensource.org/licenses/MIT)
[](https://angular.io)
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
```bash
npm install ng-angular-popup
```
## Quick Start
### 1. Basic Setup (Zoneless Mode - Recommended)
```typescript
// 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:
```typescript
// 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
```typescript
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:
```typescript
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:
```html
<ng-toast [position]="TOAST_POSITIONS.TOP_RIGHT" [width]="350"></ng-toast>
```
3. Inject and use the service in your components:
```typescript
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
```typescript
// 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
```typescript
// 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:
```scss
// 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
```typescript
// 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](LICENSE) file for details.
## Author
Sashikumar Yadav
- Email: yshashi30@gmail.com
- GitHub: [@yshashi](https://github.com/yshashi)
## Support
If you like this project, please consider giving it a ⭐️ on [GitHub](https://github.com/yshashi/ng-angular-popup)!