Notifications

@su-labs/notifications

A highly customizable Angular notification library built with modern practices, including reactive Signals. Easily display different types of notifications with various positions, custom icons, and optional auto-closing behavior.

📚 Table of Contents

• Why Use This Library?
• Features
• Installation
• Quick Start
• Usage
• API Reference
• Configuration Options
• How It Works
• Browser Compatibility
• Related Libraries
• Troubleshooting
• Support
• Contributing
• License

💡 Why Use This Library?

• 🎯 Lightweight - Minimal bundle size
• ⚡ Reactive - Built with Angular Signals
• 🎨 Customizable - Multiple themes and positions
• 🖼️ Icon Support - Default SVG or custom icons
• ⏱️ Auto-dismiss - Configurable duration
• 🔒 Type-Safe - Full TypeScript support
• 📦 Zero Dependencies - No bloat
• 🧪 Well Tested - Comprehensive test coverage
• 📝 Well Documented - Clear examples and API docs

Features

• Reactive Core: Built on Angular Signals for optimal performance and reactive updates.
• Multiple Positions: Notifications can be displayed in six different positions (top-right, top-left, bottom-right, bottom-left, top-center, bottom-center).
• Customizable: Easily change themes, icons, and CSS classes to match your application's design system.
• Icon Support:
  • Default Icons: Render a default SVG icon based on the notification type.
  • Custom Icons: Use a custom SVG string or an image URL as an icon.
• Dismissible: Notifications can be dismissed manually or set to auto-close after a specified duration.
• Declarative Usage: Add a single component to your root template and use the service from anywhere in your application.

Installation

You can install this library via npm:

npm install @su-labs/notifications

Peer Dependencies

This library requires the following peer dependencies:

npm install @angular/common@^21 @angular/core@^21

🚀 Quick Start

// 1. Install
npm install @su-labs/notifications

// 2. Add component to your app template
// app.component.html
<su-notifications></su-notifications>
<router-outlet></router-outlet>

// 3. Show notifications from any component
import { Component, inject } from '@angular/core';
import { SuNotificationService } from '@su-labs/notifications';

@Component({
  template: `<button (click)="showSuccess()">Show Success</button>`
})
export class AppComponent {
  notificationService = inject(SuNotificationService);

  showSuccess() {
    this.notificationService.show({
      type: 'success',
      message: 'Operation completed!'
    });
  }
}

Usage

1. Add the component to your application

Add the <su-notifications></su-notifications> component to your root AppComponent or index.html file. This component acts as a container for all notifications.

<!-- src/app/app.component.html -->
<su-notifications></su-notifications>
<router-outlet></router-outlet>

2. Inject the service and show a notification

Inject the SuNotificationService into any component or service and call its show() method to display a new notification.

// src/app/my-example.component.ts
import { Component, inject } from '@angular/core';
import { CommonModule } from '@angular/common';
import { SuNotificationService } from '@su-labs/notifications';

@Component({
  selector: 'app-my-example',
  standalone: true,
  imports: [CommonModule],
  template: `
    <div class="example-container">
      <button (click)="showSuccess()">Show Success</button>
      <button (click)="showError()">Show Error</button>
      <button (click)="showCustom()">Show Custom Icon</button>
    </div>
  `
})
export class MyExampleComponent {
  private readonly notificationService = inject(SuNotificationService);

  showSuccess(): void {
    this.notificationService.show({
      type: 'success',
      message: 'Your action was successful!'
    });
  }

  showError(): void {
    this.notificationService.show({
      type: 'error',
      message: 'Something went wrong. Please try again.'
    });
  }

  showCustom(): void {
    this.notificationService.show({
      type: 'info',
      message: 'This is a custom icon notification.',
      icon: `<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polygon points="13 2 3 14 12 14 11 22 21 10 12 10 13 2"></polygon></svg>`
    });
  }
}

3. Customize the position

You can configure the global position of all notifications by directly setting the position property on the service instance. This is best done during application initialization.

// src/app/app.config.ts
import { ApplicationConfig, inject, provideAppInitializer } from '@angular/core';
import { SuNotificationService } from '@su-labs/notifications';

export const appConfig: ApplicationConfig = {
  providers: [
    provideAppInitializer(() => {
      const notificationService = inject(SuNotificationService);
      notificationService.position = 'bottom-left';
    }),
    // other providers
  ],
};

📖 API Reference

Service (SuNotificationService)

Properties

| Property | Type | Description | |----------|------|-------------| | position | NotificationPosition | Global notification position |

Methods

| Method | Parameters | Description | |--------|------------|-------------| | show(config) | NotificationConfig | Display a new notification | | dismiss(id) | string | Manually dismiss a notification |

Types

type NotificationType = 'info' | 'success' | 'warning' | 'error' | 'custom';

type NotificationPosition = 
  | 'top-right' 
  | 'top-left' 
  | 'bottom-right' 
  | 'bottom-left' 
  | 'top-center' 
  | 'bottom-center';

interface NotificationConfig {
  type: NotificationType;
  message: string;
  duration?: number;        // Default: 3000ms
  autoClose?: boolean;      // Default: true
  cssClass?: string;        // Custom CSS class
  icon?: string;            // Custom SVG string or image URL
}

Configuration Options

Notification Types

| Type | Description | Default Icon | |------|-------------|--------------| | info | Informational message | ℹ️ | | success | Success message | ✅ | | warning | Warning message | ⚠️ | | error | Error message | ❌ | | custom | Custom styled message | 🔔 |

Positions

| Position | Description | |----------|-------------| | top-right | Top right corner (default) | | top-left | Top left corner | | top-center | Top center | | bottom-right | Bottom right corner | | bottom-left | Bottom left corner | | bottom-center | Bottom center |

How It Works

The library consists of a stateless service (SuNotificationService) and a presentational component (SuNotificationComponent).

The service manages a list of notifications using a private Signal. When you call service.show(), it adds a new notification object to the signal's array. The component then reads from this signal and automatically renders a notification for each item in the array. This approach keeps the state management decoupled from the UI, making it highly flexible and testable.

The component's icons are rendered using [innerHTML] to safely inject SVG markup into the template. Angular's DomSanitizer is used to prevent security risks like Cross-Site Scripting (XSS) attacks.

🌐 Browser Compatibility

Works in all modern browsers that support:

• ✅ CSS Flexbox
• ✅ CSS Animations
• ✅ Angular 21+
• ✅ ES2022+

| Browser | Version | |---------|---------| | Chrome | ≥ 90 | | Firefox | ≥ 88 | | Safari | ≥ 14 | | Edge | ≥ 90 |

🔗 Related Libraries

Part of the @su-labs suite:

• 👀 @su-labs/visit-tracker - User visit tracking
• 🎨 @su-labs/theme - Theme management with dark mode support
• 🔍 @su-labs/scroll-spy - Scroll position tracking
• 📏 @su-labs/font-size - Accessible font size controls

🔧 Troubleshooting

Notifications not showing?

Make sure you've added <su-notifications></su-notifications> to your root component template.

Icons not displaying?

If using custom icons, ensure the SVG string is valid. For security, Angular sanitizes HTML by default.

Position not changing?

Set the position property during app initialization using provideAppInitializer.

TypeScript errors?

Ensure you have Angular 21+ and TypeScript 5.7+ installed.

💬 Support

• 🐛 Found a bug? Open an issue
• 💡 Have a feature request? Start a discussion
• ⭐ Like this library? Give it a star!

Contributing

If you find any bugs or have feature requests, please open an issue or submit a pull request on our GitHub repository.

To contribute code, please ensure your changes include unit tests to maintain code quality. Please see the main repository's README.md for details on the monorepo structure.

License

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