Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/scttcper/ngx-toastr

๐Ÿž Angular Toastr
https://github.com/scttcper/ngx-toastr

angular angular2 aot-compilation ngmodule toastr typescript

Last synced: 3 days ago
JSON representation

๐Ÿž Angular Toastr

Awesome Lists containing this project

README

        


Angular Toastr


ngx-toastr





npm


codecov





DEMO: https://ngx-toastr.vercel.app

## Features

- Toast Component Injection without being passed `ViewContainerRef`
- No use of `*ngFor`. Fewer dirty checks and higher performance.
- AoT compilation and lazy loading compatible
- Component inheritance for custom toasts
- SystemJS/UMD rollup bundle
- Animations using Angular's
[Web Animations API](https://angular.io/docs/ts/latest/guide/animations.html)
- Output toasts to an optional target directive

## Dependencies

Latest version available for each version of Angular

| ngx-toastr | Angular |
| ---------- | ----------- |
| 13.2.1 | 10.x 11.x |
| 14.3.0 | 12.x 13.x |
| 15.2.2 | 14.x. |
| 16.2.0 | 15.x |
| 17.0.2 | 16.x |
| current | >= 17.x |

## Install

```bash
npm install ngx-toastr --save
```

`@angular/animations` package is a required dependency for the default toast

```bash
npm install @angular/animations --save
```

Don't want to use `@angular/animations`? See
[Setup Without Animations](#setup-without-animations).

## Setup

**step 1:** add css

- copy
[toast css](/src/lib/toastr.css)
to your project.
- If you are using sass you can import the css.

```scss
// regular style toast
@import 'ngx-toastr/toastr';

// bootstrap style toast
// or import a bootstrap 4 alert styled design (SASS ONLY)
// should be after your bootstrap imports, it uses bs4 variables, mixins, functions
@import 'ngx-toastr/toastr-bs4-alert';

// if you'd like to use it without importing all of bootstrap it requires
@import 'bootstrap/scss/functions';
@import 'bootstrap/scss/variables';
@import 'bootstrap/scss/mixins';
// bootstrap 4
@import 'ngx-toastr/toastr-bs4-alert';
// boostrap 5
@import 'ngx-toastr/toastr-bs5-alert';
```

- If you are using angular-cli you can add it to your angular.json

```ts
"styles": [
"styles.scss",
"node_modules/ngx-toastr/toastr.css" // try adding '../' if you're using angular cli before 6
]
```

**step 2:** add `ToastrModule` to app `NgModule`, or `provideToastr` to providers, make sure you have `BrowserAnimationsModule` (or `provideAnimations`) as well.

- Module based

```typescript
import { CommonModule } from '@angular/common';
import { BrowserAnimationsModule } from '@angular/platform-browser/animations';

import { ToastrModule } from 'ngx-toastr';

@NgModule({
imports: [
CommonModule,
BrowserAnimationsModule, // required animations module
ToastrModule.forRoot(), // ToastrModule added
],
bootstrap: [App],
declarations: [App],
})
class MainModule {}
```

- Standalone

```typescript
import { AppComponent } from './src/app.component';
import { provideAnimations } from '@angular/platform-browser/animations';

import { provideToastr } from 'ngx-toastr';

bootstrapApplication(AppComponent, {
providers: [
provideAnimations(), // required animations providers
provideToastr(), // Toastr providers
]
});
```

## Use

```typescript
import { ToastrService } from 'ngx-toastr';

@Component({...})
export class YourComponent {
constructor(private toastr: ToastrService) {}

showSuccess() {
this.toastr.success('Hello world!', 'Toastr fun!');
}
}
```

## Options

There are **individual options** and **global options**.

### Individual Options

Passed to `ToastrService.success/error/warning/info/show()`

| Option | Type | Default | Description
| ----------------- | ------------------------------ | ------------------------------ | ------------------------------------------------- |
| toastComponent | Component | Toast | Angular component that will be used |
| closeButton | boolean | false | Show close button |
| timeOut | number | 5000 | Time to live in milliseconds |
| extendedTimeOut | number | 1000 | Time to close after a user hovers over toast |
| disableTimeOut | `boolean \| 'timeOut' \| 'extendedTimeOut'` | false | Disable both timeOut and extendedTimeOut when set to `true`. Allows specifying which timeOut to disable, either: `timeOut` or `extendedTimeOut` |
| easing | string | 'ease-in' | Toast component easing |
| easeTime | string \| number | 300 | Time spent easing |
| enableHtml | boolean | false | Allow html in message |
| newestOnTop | boolean | true | New toast placement |
| progressBar | boolean | false | Show progress bar |
| progressAnimation | `'decreasing' \| 'increasing'` | 'decreasing' | Changes the animation of the progress bar. |
| toastClass | string | 'ngx-toastr' | CSS class(es) for toast |
| positionClass | string | 'toast-top-right' | CSS class(es) for toast container |
| titleClass | string | 'toast-title' | CSS class(es) for inside toast on title |
| messageClass | string | 'toast-message' | CSS class(es) for inside toast on message |
| tapToDismiss | boolean | true | Close on click |
| onActivateTick | boolean | false | Fires `changeDetectorRef.detectChanges()` when activated. Helps show toast from asynchronous events outside of Angular's change detection |

#### Setting Individual Options

success, error, info, warning take `(message, title, ToastConfig)` pass an
options object to replace any default option.

```typescript
this.toastrService.error('everything is broken', 'Major Error', {
timeOut: 3000,
});
```

### Global Options

All [individual options](#individual-options) can be overridden in the global
options to affect all toasts. In addition, global options include the following
options:

| Option | Type | Default | Description |
| ----------------------- | ------- | ---------------------------------- | ------------------------------------------------------------------ |
| maxOpened | number | 0 | Max toasts opened. Toasts will be queued. 0 is unlimited |
| autoDismiss | boolean | false | Dismiss current toast when max is reached |
| iconClasses | object | [see below](#iconclasses-defaults) | Classes used on toastr service methods |
| preventDuplicates | boolean | false | Block duplicate messages |
| countDuplicates | boolean | false | Displays a duplicates counter (preventDuplicates must be true). Toast must have a title and duplicate message |
| resetTimeoutOnDuplicate | boolean | false | Reset toast timeout on duplicate (preventDuplicates must be true) |
| includeTitleDuplicates | boolean | false | Include the title of a toast when checking for duplicates (by default only message is compared) |

##### iconClasses defaults

```typescript
iconClasses = {
error: 'toast-error',
info: 'toast-info',
success: 'toast-success',
warning: 'toast-warning',
};
```

#### Setting Global Options

Pass values to `ToastrModule.forRoot()` or `provideToastr()` to set global options.

- Module based

```typescript
// root app NgModule
imports: [
ToastrModule.forRoot({
timeOut: 10000,
positionClass: 'toast-bottom-right',
preventDuplicates: true,
}),
],
```

- Standalone

```typescript
import { AppComponent } from './src/app.component';
import { provideAnimations } from '@angular/platform-browser/animations';

import { provideToastr } from 'ngx-toastr';

bootstrapApplication(AppComponent, {
providers: [
provideToastr({
timeOut: 10000,
positionClass: 'toast-bottom-right',
preventDuplicates: true,
}),
]
});
```

### Toastr Service methods return:

```typescript
export interface ActiveToast {
/** Your Toast ID. Use this to close it individually */
toastId: number;
/** the title of your toast. Stored to prevent duplicates if includeTitleDuplicates set */
title: string;
/** the message of your toast. Stored to prevent duplicates */
message: string;
/** a reference to the component see portal.ts */
portal: ComponentRef;
/** a reference to your toast */
toastRef: ToastRef;
/** triggered when toast is active */
onShown: Observable;
/** triggered when toast is destroyed */
onHidden: Observable;
/** triggered on toast click */
onTap: Observable;
/** available for your use in custom toast */
onAction: Observable;
}
```

### Put toasts in your own container

Put toasts in a specific div inside your application. This should probably be
somewhere that doesn't get deleted. Add `ToastContainerModule` to the ngModule
where you need the directive available. Make sure that your container has
an `aria-live="polite"` attribute, so that any time a toast is injected into
the container it is announced by screen readers.

```typescript
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { BrowserAnimationsModule } from '@angular/platform-browser/animations';

import { ToastrModule, ToastContainerModule } from 'ngx-toastr';

import { AppComponent } from './app.component';

@NgModule({
declarations: [AppComponent],
imports: [
BrowserModule,
BrowserAnimationsModule,

ToastrModule.forRoot({ positionClass: 'inline' }),
ToastContainerModule,
],
providers: [],
bootstrap: [AppComponent],
})
export class AppModule {}
```

Add a div with `toastContainer` directive on it.

```typescript
import { Component, OnInit, ViewChild } from '@angular/core';

import { ToastContainerDirective, ToastrService } from 'ngx-toastr';

@Component({
selector: 'app-root',
template: `

Click



`,
})
export class AppComponent implements OnInit {
@ViewChild(ToastContainerDirective, { static: true })
toastContainer: ToastContainerDirective;

constructor(private toastrService: ToastrService) {}
ngOnInit() {
this.toastrService.overlayContainer = this.toastContainer;
}
onClick() {
this.toastrService.success('in div');
}
}
```

## Functions

##### Clear

Remove all or a single toast by optional id

```ts
toastrService.clear(toastId?: number);
```

##### Remove

Remove and destroy a single toast by id

```
toastrService.remove(toastId: number);
```

## SystemJS

If you are using SystemJS, you should also adjust your configuration to point to
the UMD bundle.

In your SystemJS config file, `map` needs to tell the System loader where to
look for `ngx-toastr`:

```js
map: {
'ngx-toastr': 'node_modules/ngx-toastr/bundles/ngx-toastr.umd.min.js',
}
```

## Setup Without Animations

If you do not want to include `@angular/animations` in your project you can
override the default toast component in the global config to use
`ToastNoAnimation` instead of the default one.

In your main module (ex: `app.module.ts`)

```typescript
import { ToastrModule, ToastNoAnimation, ToastNoAnimationModule } from 'ngx-toastr';

@NgModule({
imports: [
// ...

// BrowserAnimationsModule no longer required
ToastNoAnimationModule.forRoot(),
],
// ...
})
class AppModule {}
```

That's it! Animations are no longer required.

## Using A Custom Toast

Create your toast component extending Toast see the demo's pink toast for an example
https://github.com/scttcper/ngx-toastr/blob/master/src/app/pink.toast.ts

```typescript
import { ToastrModule } from 'ngx-toastr';

@NgModule({
imports: [
ToastrModule.forRoot({
toastComponent: YourToastComponent, // added custom toast!
}),
],
bootstrap: [App],
declarations: [App, YourToastComponent], // add!
})
class AppModule {}
```

## FAQ

1. ExpressionChangedAfterItHasBeenCheckedError: Expression has changed after it
was checked\
When opening a toast inside an angular lifecycle wrap it in setTimeout

```typescript
ngOnInit() {
setTimeout(() => this.toastr.success('sup'))
}
```

2. Change default icons (check, warning sign, etc)\
Overwrite the css background-image: https://github.com/scttcper/ngx-toastr/blob/master/src/lib/toastr.css.
3. How do I use this in an ErrorHandler?\
See: https://github.com/scttcper/ngx-toastr/issues/179.
4. How can I translate messages?\
See: https://github.com/scttcper/ngx-toastr/issues/201.
5. How to handle toastr click/tap action?
```ts
showToaster() {
this.toastr.success('Hello world!', 'Toastr fun!')
.onTap
.pipe(take(1))
.subscribe(() => this.toasterClickedHandler());
}

toasterClickedHandler() {
console.log('Toastr clicked');
}
```
6. How to customize styling without overridding defaults?\
Add multiple CSS classes separated by a space:
```ts
toastClass: 'yourclass ngx-toastr'
```
See: https://github.com/scttcper/ngx-toastr/issues/594.

## Previous Works

[toastr](https://github.com/CodeSeven/toastr) original toastr\
[angular-toastr](https://github.com/Foxandxss/angular-toastr) AngularJS toastr\
[notyf](https://github.com/caroso1222/notyf) notyf (css)

## License

MIT

---

> GitHub [@scttcper](https://github.com/scttcper) ย ยทย 
> Twitter [@scttcper](https://twitter.com/scttcper)