Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://scttcper.github.io/ngx-toastr
🍞 Angular Toastr
https://scttcper.github.io/ngx-toastr
angular angular2 aot-compilation ngmodule toastr typescript
Last synced: 3 months ago
JSON representation
🍞 Angular Toastr
- Host: GitHub
- URL: https://scttcper.github.io/ngx-toastr
- Owner: scttcper
- License: mit
- Created: 2016-07-28T17:19:43.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2023-11-16T04:24:31.000Z (about 1 year ago)
- Last Synced: 2024-05-21T07:45:57.370Z (7 months ago)
- Topics: angular, angular2, aot-compilation, ngmodule, toastr, typescript
- Language: TypeScript
- Homepage: https://ngx-toastr.vercel.app
- Size: 5.97 MB
- Stars: 2,467
- Watchers: 31
- Forks: 360
- Open Issues: 62
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
ngx-toastr
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)