## Overview
Angular Notifier is a notification library designed to provide elegant, non-intrusive notifications for your Angular applications. With built-in animations, multiple themes, and extensive customization options, it helps you deliver a polished user experience without the complexity.
**Key highlights:**
- **Highly customizable** - Configure positioning, behavior, animations, and appearance
- **Fully animated** - Smooth slide and fade animations with customizable timing
- **Multiple themes** - Material Design, Bootstrap, and PrimeNG-inspired styles out of the box
- **Type-safe** - Written in TypeScript with full type definitions
- **Lightweight** - Zero dependencies beyond Angular itself
- **Production-ready** - Battle-tested and actively maintained
- **Module & Standalone support** - Works with both traditional NgModule and modern standalone components
## Features
- **Rich notification types**: Success, error, warning, info, and custom types
- **Flexible positioning**: Top, bottom, left, right, or center placement
- **Smart behavior**: Auto-hide, stacking, pause on hover, and click handlers
- **Animation presets**: Built-in fade and slide animations with customizable easing
- **Multiple themes**: Material Design, Bootstrap-style, and PrimeNG-inspired themes
- **Responsive design**: Mobile-optimized with responsive breakpoints
- **Custom templates**: Use your own HTML templates for complete control
- **Notification control**: Show, hide, and manage notifications programmatically
- **Accessibility**: Keyboard navigation and ARIA support
## Installation
Install via npm:
```bash
npm install gramli-angular-notifier
```
### Angular Version Compatibility
| Angular Notifier | Angular |
| ---------------- | ------- |
| `21.x` | `21.x` |
| `18.x` | `20.x` |
| `17.x` | `19.x` |
| `16.x` | `18.x` |
| `15.x` | `17.x` |
> **Note**: This is a maintained fork of [dominique-mueller/angular-notifier](https://github.com/dominique-mueller/angular-notifier), updated to support the latest Angular versions. For older Angular versions, see the [original repository](https://github.com/dominique-mueller/angular-notifier).
## Quick Start
### 1. Import the NotifierModule
#### For Module-Based Applications
Add the `NotifierModule` to your root module:
```typescript
import { NotifierModule } from 'gramli-angular-notifier';
@NgModule({
imports: [
// With custom configuration
NotifierModule.withConfig({
position: {
horizontal: { position: 'right', distance: 12 },
vertical: { position: 'top', distance: 12, gap: 10 }
},
theme: 'material'
}),
// Or with default configuration
NotifierModule.withConfig()
]
})
export class AppModule { }
```
> **Important**: As of version 21.1.x, you must use `NotifierModule.withConfig()` even for default configuration. Simply importing `NotifierModule` without calling `withConfig()` will not provide the required services.
#### For Standalone Components
Use the `provideNotifier()` function in your application configuration:
```typescript
// main.ts or app.config.ts
import { ApplicationConfig } from '@angular/core';
import { provideNotifier } from 'gramli-angular-notifier';
export const appConfig: ApplicationConfig = {
providers: [
// With custom configuration
provideNotifier({
position: {
horizontal: { position: 'right', distance: 12 },
vertical: { position: 'top', distance: 12, gap: 10 }
},
theme: 'material'
}),
// Or with default configuration
// provideNotifier()
]
};
```
### 2. AppComponent - Add the notifier container
#### For Module-Based Applications
Add the `` component to your app component template:
```typescript
@Component({
selector: 'app-root',
template: `
`
})
export class AppComponent { }
```
#### For Standalone Components
Add the `` component to your app component template and import `NotifierModule` in components that display notifications:
```typescript
import { Component } from '@angular/core';
import { NotifierModule } from 'gramli-angular-notifier';
@Component({
selector: 'app-root',
standalone: true,
imports: [NotifierModule], // Import for components only
template: `
`
})
export class AppComponent { }
```
### 3. Import styles
Import the styles in your global styles file (`styles.scss` or `styles.css`):
```scss
// Import all styles (core + all themes + all types)
@use 'gramli-angular-notifier/styles';
// Or import only what you need for better performance
@use 'gramli-angular-notifier/styles/core';
@use 'gramli-angular-notifier/styles/themes/theme-material';
@use 'gramli-angular-notifier/styles/types/type-success';
@use 'gramli-angular-notifier/styles/types/type-error';
```
> **Note**: The deprecated `@import` syntax still works but will show Sass deprecation warnings. We recommend using `@use` to avoid warnings in your build output.
### 4. Use the NotifierService
Inject and use the `NotifierService` in your components:
```typescript
import { NotifierService } from 'gramli-angular-notifier';
@Component({
selector: 'app-example',
template: ``
})
export class ExampleComponent {
constructor(private notifier: NotifierService) { }
showNotification() {
this.notifier.notify('success', 'You are awesome!');
}
}
```
## Live Examples
Explore complete working examples demonstrating both module-based and standalone approaches:
### 📦 [Module-Based Demo](https://github.com/Gramli/angular-notifier/tree/develop/projects/angular-notifier-demo)
Full example application using traditional NgModule architecture with `NotifierModule.withConfig()`.
### ⚡ [Standalone Demo](https://github.com/Gramli/angular-notifier/tree/develop/projects/angular-notifier-standalone-demo)
Modern standalone component example using `provideNotifier()` in application configuration.
## Themes
Angular Notifier comes with three professionally designed themes:
### Material Design Theme
Clean, modern design following Google's Material Design principles:
```typescript
NotifierModule.withConfig({ theme: 'material' })
```
- Subtle shadows and 3px border radius
- Smooth opacity transitions
- Compact and space-efficient
### Bootstrap Theme
Professional styling inspired by Bootstrap 5:
```typescript
NotifierModule.withConfig({ theme: 'bootstrap' })
```
- Alert-style contextual colors
- 6px rounded corners with layered shadows
- Responsive spacing with rem units
- Enhanced hover effects and accessibility focus states
### PrimeNG Theme
Modern, elegant design inspired by PrimeNG components:
```typescript
NotifierModule.withConfig({ theme: 'primeng' })
```
- Rich, vibrant colors with left accent border
- Multi-layered shadows for depth
- Circular close button with rotation animation
- Available in both dark and light variants (`primeng-light`)
## API
### NotifierService Methods
#### `notify(type, message, id?)`
Show a notification with the specified type and message:
```typescript
this.notifier.notify('success', 'Operation completed successfully!');
this.notifier.notify('error', 'Something went wrong', 'error-id-123');
```
#### `show(config)`
Show a notification with detailed configuration:
```typescript
this.notifier.show({
type: 'warning',
message: 'Your session will expire soon',
id: 'session-warning',
template: this.customTemplate
});
```
#### `hide(id)`
Hide a specific notification by ID:
```typescript
this.notifier.hide('notification-id');
```
#### `hideNewest()`
Hide the most recently shown notification:
```typescript
this.notifier.hideNewest();
```
#### `hideOldest()`
Hide the oldest visible notification:
```typescript
this.notifier.hideOldest();
```
#### `hideAll()`
Hide all visible notifications:
```typescript
this.notifier.hideAll();
```
### Notification Types
- `default` - Default notification style
- `info` - Informational messages
- `success` - Success confirmations
- `warning` - Warning messages
- `error` - Error alerts
## Customization
### Configuration Options
Configure Angular Notifier when importing the module:
```typescript
NotifierModule.withConfig({
position: {
horizontal: {
position: 'right', // 'left' | 'middle' | 'right'
distance: 12 // Distance from edge (px)
},
vertical: {
position: 'top', // 'top' | 'bottom'
distance: 12, // Distance from edge (px)
gap: 10 // Gap between notifications (px)
}
},
theme: 'material', // 'material' | 'bootstrap' | 'primeng' | 'primeng-light'
behaviour: {
autoHide: 5000, // Auto-hide after ms (false to disable)
onClick: 'hide', // 'hide' | false
onMouseover: 'pauseAutoHide', // 'pauseAutoHide' | 'resetAutoHide' | false
showDismissButton: true, // Show close button
stacking: 4 // Max visible notifications (false for unlimited)
},
animations: {
enabled: true,
show: {
preset: 'slide', // 'slide' | 'fade'
speed: 300, // Animation duration (ms)
easing: 'ease' // CSS easing function
},
hide: {
preset: 'fade',
speed: 300,
easing: 'ease',
offset: 50 // Stagger delay when hiding multiple (ms)
},
shift: {
speed: 300, // Duration for shifting notifications
easing: 'ease'
},
overlap: 150 // Animation overlap for smoother transitions (ms)
}
})
```
### Custom Templates
Create fully custom notification layouts using Angular templates:
```typescript
@Component({
selector: 'app-notifications',
template: `