Angular2-Toaster

angular2-toaster is an asynchronous, non-blocking, Ahead of Time Compilation-supported Angular Toaster Notification library largely based off of AngularJS-Toaster.

Version ^11.0.0 has a number of new features, type definitions, and break changesing. Please review the CHANGELOG for a list of features and breaking changes before upgrading.

Version ^5.0.0 requires either .forRoot() or .forChild() ToasterModule inclusion. Please read the 5.x.x release notes and the Getting Started section before upgrading.

Version ^4.0.0 now supports @angular/animations, which is a breaking change. Please read both the Getting Started and Animations sections before upgrading.

Demo

A dynamic Angular and Typescript demo can be found at this plunker.

Getting Started

Installation:

npm install angular2-toaster

Import CSS

Copy or Link CSS

<link rel="stylesheet" type="text/css" href="https://github.com/Stabzs/Angular2-Toaster/raw/11.0.1/node_modules/angular2-toaster/toaster.css" />

or

<link rel="stylesheet" type="text/css" href="https://github.com/Stabzs/Angular2-Toaster/raw/11.0.1/node_modules/angular2-toaster/toaster.min.css" />

Import CSS with Sass or Less

@import 'node_modules/angular2-toaster/toaster';

Compile the Library's SCSS

@import 'node_modules/angular2-toaster/toaster';

Import Library

Import via SystemJS

Within the map property of the systemjs.config file, add mappings for angular, rxjs (which is a dependency), and the angular2-toaster bundled umd file:

map: {
      // angular bundles
      '@angular/core': 'npm:@angular/core/bundles/core.umd.js',
      // ...
      // other libraries
      'rxjs':  'npm:rxjs',
      'angular2-toaster': 'npm:angular2-toaster/bundles/angular2-toaster.umd.js'

Import via Webpack

Simply follow the Getting Started instructions to import the library.

Getting Started With Default Configuration - NgModule (Recommended):

import {NgModule, Component} from '@angular/core';
import {BrowserAnimationsModule} from '@angular/platform-browser/animations';
import {ToasterModule, ToasterService} from 'angular2-toaster';
import {Root} from './root.component'

@NgModule({
    imports: [BrowserAnimationsModule, ToasterModule.forRoot()],
    declarations: [Root],
    bootstrap: [Root]
})

@Component({
    selector: 'root',
    template: `
            <toaster-container></toaster-container>
            <button (click)="popToast()">pop toast</button>`
})

export class Root {
    private toasterService: ToasterService;

    constructor(toasterService: ToasterService) {
        this.toasterService = toasterService;
    }

    popToast() {
        this.toasterService.pop('success', 'Args Title', 'Args Body');
    }
}

ToasterModule.forRoot() is recommended for most applications as it will guarantee a single instance of the ToasterService, ensuring that all recipient containers observe the same ToasterService events.

For subsequent inclusions, use ToasterModule.forChild() to provide the ToasterContainerComponent only, ensuring that ToasterService is still held as a singleton at the root.

Getting Started with Default Configuration - Manual Component Inclusion (obsolete >= 5.0.0):

import {Component} from '@angular/core';
import {BrowserAnimationsModule} from '@angular/platform-browser/animations';
import {ToasterContainerComponent, ToasterService} from 'angular2-toaster';

@Component({
    selector: 'root',
    imports: [BrowserAnimationsModule],
    directives: [ToasterContainerComponent],
    providers: [ToasterService],
    template: `
        <toaster-container></toaster-container>
        <button (click)="popToast()">pop toast</button>`
})

class Root {
    private toasterService: ToasterService;

    constructor(toasterService: ToasterService) {
        this.toasterService = toasterService;    
    }

    popToast() {
        this.toasterService.pop('success', 'Args Title', 'Args Body');
    }
}

bootstrap(Root);

Getting Started with Configuration Override:

import {Component} from '@angular/core';
import {BrowserAnimationsModule} from '@angular/platform-browser/animations';
import {ToasterModule, ToasterService, ToasterConfig} from 'angular2-toaster';

@Component({
    selector: 'root',
    imports: [BrowserAnimationsModule, ToasterModule.forRoot()],
    template: `
        <toaster-container [toasterconfig]="config">
        </toaster-container>
        <button (click)="popToast()">pop toast</button>`
})

class Root {
    private toasterService: ToasterService;

    constructor(toasterService: ToasterService) {
        this.toasterService = toasterService;    
    }

    public config: ToasterConfig = 
        new ToasterConfig({
            showCloseButton: true, 
            tapToDismiss: false, 
            timeout: 0
        });

    popToast() {
        this.toasterService.pop('success', 'Args Title', 'Args Body');
    }
}

bootstrap(Root);

Asynchronous vs Synchronous ToasterService

ToasterService exposes both a synchronous and asynchronous pop method in the form of pop() and popAsync() respectively.

pop() returns a concrete Toast instance after the toastId property has been hydrated and the toast has been added to all receiving containers.

popAsync() returns a hot Observable<Toast> that may be subscribed to to receive multiple toast updates.

Customize Toast arguments in pop

var toast: Toast = {
    type: 'success',
    title: 'close button',
    showCloseButton: true
};

this.toasterService.pop(toast);

Clear Existing Toast

ToasterService exposes a clear function that accepts two optional parameters: toastId and toastContainerId.

These parameters can be used to clear toasts by specific id, by container id, by both, or by neither. If both parameters are omitted, all toasts in all containers will be removed.

var toast = this.toasterService.pop('success', 'title', 'body');
this.toasterService.clear(toast.toastId, toast.toastContainerId);

Animations

Starting with version 4.0.0 and greater, Animation configuration is required, as described in the Getting Started section.

To add animations:

• Install the @angular/animations npm package via npm install @angular/animations.

• Add the BrowserAnimationsModule to your root module

  ```typescript import {NgModule, Component} from '@angular/core'; import {BrowserAnimationsModule} from '@angular/platform-browser/animations'; import {ToasterModule} from 'angular2-toaster';

  @NgModule({ imports: [BrowserAnimationsModule, ToasterModule], ... ```

If you want to avoid bringing in an additional module solely for the sake of animations, you can explicitly configure angular2-toaster to ignore animations. To do so, import the NoopAnimationsModule instead:

import {NoopAnimationsModule} from '@angular/platform-browser/animations';
import {ToasterModule} from 'angular2-toaster';

@NgModule({
    imports: [NoopAnimationsModule, ToasterModule],
    ...

Angular Animations require browsers that support the Web Animations Standard.

If you need to target a non-supported browser, a polyfill is required.

Configurable Options

Toast Types

By default, five toast types are defined via the ToastType type: 'error, 'info', 'wait', 'success', and 'warning'.

The existing toast type configurations can be overridden by passing a mapping object that uses the same type names but overrides the style class:

template: 
    `<toaster-container [toasterconfig]="config"></toaster-container>`

public config: ToasterConfig = 
    new ToasterConfig({typeClasses: {
      error: 'custom-toast-error',
      info: 'custom-toast-info',
      wait: 'custom-toast-wait',
      success: 'custom-toast-success',
      warning: 'custom-toast-warning'
    }});

In addition, the default options can be overridden, replaced, or expanded, by extending the toast type with a custom type and passing a mapping object to the config, where the key corresponds to the toast type and the value corresponds to a custom class:

NOTE: When providing a custom type, both the typeClasses and iconClasses objects must be updated. In the case where either are not provided, the toast type will fall back to the defaultToastType which defaults to info.

import {DefaultTypeClasses, DefaultIconClasses} from 'angular2-toaster';
type ExtendedToastType = ('partial-success') & ToastType;

template: 
    `<toaster-container [toasterconfig]="config"></toaster-container>`

extendedTypeClasses = { ...DefaultTypeClasses, ...{ 'partial-success': 'toast-partial-success' }};
extendedIconClasses = { ...DefaultIconClasses, ...{ 'partial-success': 'icon-partial-success' }};

public config: ToasterConfig = 
    new ToasterConfig({
        typeClasses: <ExtendedToastType>this.extendedTypeClasses,
        iconClasses: <ExtendedToastType>this.extendedIconClasses
    });

Animations

There are five animation styles that can be applied via the toasterconfig animation property: 'fade', 'flyLeft', 'flyRight', 'slideDown', and 'slideUp'. Any other value will disable animations.

template: 
    `<toaster-container [toasterconfig]="config"></toaster-container>`

public config: ToasterConfig = 
    new ToasterConfig({animation: 'fade'});

Limit

Limit is defaulted to null, meaning that there is no maximum number of toasts that are defined before the toast container begins removing toasts when a new toast is added.

To change this behavior, pass a "limit" option to the config:

template: 
    `<toaster-container [toasterconfig]="config"></toaster-container>`

public config: ToasterConfig = 
    new ToasterConfig({limit: 5});

Tap to Dismiss

By default, the tapToDismiss option is set to true, meaning that if a toast is clicked anywhere on the toast body, the toast will be dismissed. This behavior can be overriden in the config so that if set to false, the toast will only be dismissed if the close button is defined and clicked:

template: 
    `<toaster-container [toasterconfig]="config"></toaster-container>`

public config: ToasterConfig = 
    new ToasterConfig({tapToDismiss: false});

Container Position

There are nine pre-built toaster container position configurations:

'toast-top-full-width', 'toast-bottom-full-width', 'toast-center',
'toast-top-left', 'toast-top-center', 'toast-top-right',
'toast-bottom-left', 'toast-bottom-center', 'toast-bottom-right'

By default, 'toast-top-right' will be used. You can specify an override (or your own custom position class that correlates to your CSS) via the positionClass property:

template: 
    `<toaster-container [toasterconfig]="config"></toaster-container>`

public config: ToasterConfig = 
    new ToasterConfig({positionClass: 'toast-top-left'});

Close Button

The Close Button's visibility can be configured at three different levels:

• Globally in the config for all toast types:

  ``typescript template:`

  public config: ToasterConfig = new ToasterConfig({showCloseButton: true}); ```

• Per info-class type: By passing the close-button configuration as an object instead of a boolean, you can specify the global behavior an info-class type should have.

  ``typescript template:`

  public config: ToasterConfig = new ToasterConfig({ showCloseButton: { 'warning': true, 'error': false } }); ```

  If a type is not defined and specified, the default behavior for that type is false.

• Per toast constructed via Toast object creation:

  ```typescript var toast : Toast = { type: 'error', title: 'Title text', body: 'Body text', showCloseButton: true };

  this.toasterService.pop(toast);

  ```

  This option is given the most weight and will override the global configurations for that toast. However, it will not persist to other toasts of that type and does not alter or pollute the global configuration.

Close Html

The close button html can be overridden either globally or per toast call.

• Globally:

  ``typescript template:`

  public config: ToasterConfig = new ToasterConfig({ closeHtml: 'Close' }); ```

• Per toast:

  ```typescript var toast : Toast = { type: 'error', title: 'Title text', body: 'Body text', showCloseButton: true, closeHtml: 'Close' };

  this.toasterService.pop(toast); ```

Newest Toasts on Top

The newestOnTop option is defaulted to true, adding new toasts on top of other existing toasts. If changed to false via the con