1 | <div align="center">
|
2 | <img src="https://raw.githubusercontent.com/scttcper/ngx-toastr/master/misc/documentation-assets/ngx-toastr-example.png" width="300" alt="Angular Toastr">
|
3 | <br>
|
4 | <h1>ngx-toastr</h1>
|
5 | <br>
|
6 | <a href="https://www.npmjs.org/package/ngx-toastr">
|
7 | <img src="https://badge.fury.io/js/ngx-toastr.svg" alt="npm">
|
8 | </a>
|
9 | <a href="https://circleci.com/gh/scttcper/ngx-toastr">
|
10 | <img src="https://circleci.com/gh/scttcper/ngx-toastr.svg?style=svg" alt="circleci">
|
11 | </a>
|
12 | <a href="https://codecov.io/github/scttcper/ngx-toastr">
|
13 | <img src="https://img.shields.io/codecov/c/github/scttcper/ngx-toastr.svg" alt="codecov">
|
14 | </a>
|
15 | <br>
|
16 | <br>
|
17 | </div>
|
18 |
|
19 | DEMO: https://ngx-toastr.vercel.app
|
20 |
|
21 | ## Features
|
22 |
|
23 | - Toast Component Injection without being passed `ViewContainerRef`
|
24 | - No use of `*ngFor`. Fewer dirty checks and higher performance.
|
25 | - AoT compilation and lazy loading compatible
|
26 | - Component inheritance for custom toasts
|
27 | - SystemJS/UMD rollup bundle
|
28 | - Animations using Angular's
|
29 | [Web Animations API](https://angular.io/docs/ts/latest/guide/animations.html)
|
30 | - Output toasts to an optional target directive
|
31 |
|
32 | ## Dependencies
|
33 |
|
34 | Latest version available for each version of Angular
|
35 |
|
36 | | ngx-toastr | Angular |
|
37 | | ---------- | ----------- |
|
38 | | 6.5.0 | 4.x |
|
39 | | 8.10.2 | 5.x |
|
40 | | 10.1.0 | 8.x 7.x 6.x |
|
41 | | 11.3.3 | 8.x |
|
42 | | 12.1.0 | 9.x |
|
43 | | 13.2.1 | 10.x 11.x |
|
44 | | current | >= 12.x |
|
45 |
|
46 | ## Install
|
47 |
|
48 | ```bash
|
49 | npm install ngx-toastr --save
|
50 | ```
|
51 |
|
52 | `@angular/animations` package is a required dependency for the default toast
|
53 |
|
54 | ```bash
|
55 | npm install @angular/animations --save
|
56 | ```
|
57 |
|
58 | Don't want to use `@angular/animations`? See
|
59 | [Setup Without Animations](#setup-without-animations).
|
60 |
|
61 | ## Setup
|
62 |
|
63 | **step 1:** add css
|
64 |
|
65 | - copy
|
66 | [toast css](/src/lib/toastr.css)
|
67 | to your project.
|
68 | - If you are using sass you can import the css.
|
69 |
|
70 | ```scss
|
71 | // regular style toast
|
72 | @import '~ngx-toastr/toastr';
|
73 |
|
74 | // bootstrap style toast
|
75 | // or import a bootstrap 4 alert styled design (SASS ONLY)
|
76 | // should be after your bootstrap imports, it uses bs4 variables, mixins, functions
|
77 | @import '~ngx-toastr/toastr-bs4-alert';
|
78 |
|
79 | // if you'd like to use it without importing all of bootstrap it requires
|
80 | @import '~bootstrap/scss/functions';
|
81 | @import '~bootstrap/scss/variables';
|
82 | @import '~bootstrap/scss/mixins';
|
83 | @import '~ngx-toastr/toastr-bs4-alert';
|
84 | ```
|
85 |
|
86 | - If you are using angular-cli you can add it to your angular.json
|
87 |
|
88 | ```ts
|
89 | "styles": [
|
90 | "styles.scss",
|
91 | "node_modules/ngx-toastr/toastr.css" // try adding '../' if you're using angular cli before 6
|
92 | ]
|
93 | ```
|
94 |
|
95 | **step 2:** add ToastrModule to app NgModule, make sure you have BrowserAnimationsModule as well
|
96 |
|
97 | ```typescript
|
98 | import { CommonModule } from '@angular/common';
|
99 | import { BrowserAnimationsModule } from '@angular/platform-browser/animations';
|
100 |
|
101 | import { ToastrModule } from 'ngx-toastr';
|
102 |
|
103 | @NgModule({
|
104 | imports: [
|
105 | CommonModule,
|
106 | BrowserAnimationsModule, // required animations module
|
107 | ToastrModule.forRoot(), // ToastrModule added
|
108 | ],
|
109 | bootstrap: [App],
|
110 | declarations: [App],
|
111 | })
|
112 | class MainModule {}
|
113 | ```
|
114 |
|
115 | ## Use
|
116 |
|
117 | ```typescript
|
118 | import { ToastrService } from 'ngx-toastr';
|
119 |
|
120 | @Component({...})
|
121 | export class YourComponent {
|
122 | constructor(private toastr: ToastrService) {}
|
123 |
|
124 | showSuccess() {
|
125 | this.toastr.success('Hello world!', 'Toastr fun!');
|
126 | }
|
127 | }
|
128 | ```
|
129 |
|
130 | ## Options
|
131 |
|
132 | There are **individual options** and **global options**.
|
133 |
|
134 | ### Individual Options
|
135 |
|
136 | Passed to `ToastrService.success/error/warning/info/show()`
|
137 |
|
138 | | Option | Type | Default | Description
|
139 | | ----------------- | ------------------------------ | ------------------------------ | ------------------------------------------------- |
|
140 | | toastComponent | Component | Toast | Angular component that will be used |
|
141 | | closeButton | boolean | false | Show close button |
|
142 | | timeOut | number | 5000 | Time to live in milliseconds |
|
143 | | extendedTimeOut | number | 1000 | Time to close after a user hovers over toast |
|
144 | | disableTimeOut | `boolean \| 'timeOut' \| 'extendedTimeOut'` | false | Disable both timeOut and extendedTimeOut when set to `true`. Allows specifying which timeOut to disable, either: `timeOut` or `extendedTimeOut` |
|
145 | | easing | string | 'ease-in' | Toast component easing |
|
146 | | easeTime | string \| number | 300 | Time spent easing |
|
147 | | enableHtml | boolean | false | Allow html in message |
|
148 | | progressBar | boolean | false | Show progress bar |
|
149 | | progressAnimation | `'decreasing' \| 'increasing'` | 'decreasing' | Changes the animation of the progress bar. |
|
150 | | toastClass | string | 'ngx-toastr' | Class on toast |
|
151 | | positionClass | string | 'toast-top-right' | Class on toast container |
|
152 | | titleClass | string | 'toast-title' | Class inside toast on title |
|
153 | | messageClass | string | 'toast-message' | Class inside toast on message |
|
154 | | tapToDismiss | boolean | true | Close on click |
|
155 | | onActivateTick | boolean | false | Fires `changeDetectorRef.detectChanges()` when activated. Helps show toast from asynchronous events outside of Angular's change detection |
|
156 |
|
157 | #### Setting Individual Options
|
158 |
|
159 | success, error, info, warning take `(message, title, ToastConfig)` pass an
|
160 | options object to replace any default option.
|
161 |
|
162 | ```typescript
|
163 | this.toastrService.error('everything is broken', 'Major Error', {
|
164 | timeOut: 3000,
|
165 | });
|
166 | ```
|
167 |
|
168 | ### Global Options
|
169 |
|
170 | All [individual options](#individual-options) can be overridden in the global
|
171 | options to affect all toasts. In addition, global options include the following
|
172 | options:
|
173 |
|
174 | | Option | Type | Default | Description |
|
175 | | ----------------------- | ------- | ---------------------------------- | ------------------------------------------------------------------ |
|
176 | | maxOpened | number | 0 | Max toasts opened. Toasts will be queued. 0 is unlimited |
|
177 | | autoDismiss | boolean | false | Dismiss current toast when max is reached |
|
178 | | iconClasses | object | [see below](#iconclasses-defaults) | Classes used on toastr service methods |
|
179 | | newestOnTop | boolean | true | New toast placement |
|
180 | | preventDuplicates | boolean | false | Block duplicate messages |
|
181 | | countDuplicates | boolean | false | Displays a duplicates counter (preventDuplicates must be true). Toast must have a title and duplicate message |
|
182 | | resetTimeoutOnDuplicate | boolean | false | Reset toast timeout on duplicate (preventDuplicates must be true) |
|
183 | | includeTitleDuplicates | boolean | false | Include the title of a toast when checking for duplicates (by default only message is compared) |
|
184 |
|
185 | ##### iconClasses defaults
|
186 |
|
187 | ```typescript
|
188 | iconClasses = {
|
189 | error: 'toast-error',
|
190 | info: 'toast-info',
|
191 | success: 'toast-success',
|
192 | warning: 'toast-warning',
|
193 | };
|
194 | ```
|
195 |
|
196 | #### Setting Global Options
|
197 |
|
198 | Pass values to `ToastrModule.forRoot()`
|
199 |
|
200 | ```typescript
|
201 | // root app NgModule
|
202 | imports: [
|
203 | ToastrModule.forRoot({
|
204 | timeOut: 10000,
|
205 | positionClass: 'toast-bottom-right',
|
206 | preventDuplicates: true,
|
207 | }),
|
208 | ],
|
209 | ```
|
210 |
|
211 | ### Toastr Service methods return:
|
212 |
|
213 | ```typescript
|
214 | export interface ActiveToast {
|
215 | /** Your Toast ID. Use this to close it individually */
|
216 | toastId: number;
|
217 | /** the title of your toast. Stored to prevent duplicates if includeTitleDuplicates set */
|
218 | title: string;
|
219 | /** the message of your toast. Stored to prevent duplicates */
|
220 | message: string;
|
221 | /** a reference to the component see portal.ts */
|
222 | portal: ComponentRef<any>;
|
223 | /** a reference to your toast */
|
224 | toastRef: ToastRef<any>;
|
225 | /** triggered when toast is active */
|
226 | onShown: Observable<any>;
|
227 | /** triggered when toast is destroyed */
|
228 | onHidden: Observable<any>;
|
229 | /** triggered on toast click */
|
230 | onTap: Observable<any>;
|
231 | /** available for your use in custom toast */
|
232 | onAction: Observable<any>;
|
233 | }
|
234 | ```
|
235 |
|
236 | ### Put toasts in your own container
|
237 |
|
238 | Put toasts in a specific div inside your application. This should probably be
|
239 | somewhere that doesn't get deleted. Add `ToastContainerModule` to the ngModule
|
240 | where you need the directive available. Make sure that your container has
|
241 | an `aria-live="polite"` attribute, so that any time a toast is injected into
|
242 | the container it is announced by screen readers.
|
243 |
|
244 | ```typescript
|
245 | import { BrowserModule } from '@angular/platform-browser';
|
246 | import { NgModule } from '@angular/core';
|
247 | import { BrowserAnimationsModule } from '@angular/platform-browser/animations';
|
248 |
|
249 | import { ToastrModule, ToastContainerModule } from 'ngx-toastr';
|
250 |
|
251 | import { AppComponent } from './app.component';
|
252 |
|
253 | @NgModule({
|
254 | declarations: [AppComponent],
|
255 | imports: [
|
256 | BrowserModule,
|
257 | BrowserAnimationsModule,
|
258 |
|
259 | ToastrModule.forRoot({ positionClass: 'inline' }),
|
260 | ToastContainerModule,
|
261 | ],
|
262 | providers: [],
|
263 | bootstrap: [AppComponent],
|
264 | })
|
265 | export class AppModule {}
|
266 | ```
|
267 |
|
268 | Add a div with `toastContainer` directive on it.
|
269 |
|
270 | ```typescript
|
271 | import { Component, OnInit, ViewChild } from '@angular/core';
|
272 |
|
273 | import { ToastContainerDirective, ToastrService } from 'ngx-toastr';
|
274 |
|
275 | @Component({
|
276 | selector: 'app-root',
|
277 | template: `
|
278 | <h1><a (click)="onClick()">Click</a></h1>
|
279 | <div aria-live="polite" toastContainer></div>
|
280 | `,
|
281 | })
|
282 | export class AppComponent implements OnInit {
|
283 | @ViewChild(ToastContainerDirective, { static: true })
|
284 | toastContainer: ToastContainerDirective;
|
285 |
|
286 | constructor(private toastrService: ToastrService) {}
|
287 | ngOnInit() {
|
288 | this.toastrService.overlayContainer = this.toastContainer;
|
289 | }
|
290 | onClick() {
|
291 | this.toastrService.success('in div');
|
292 | }
|
293 | }
|
294 | ```
|
295 |
|
296 | ## Functions
|
297 |
|
298 | ##### Clear
|
299 |
|
300 | Remove all or a single toast by optional id
|
301 |
|
302 | ```ts
|
303 | toastrService.clear(toastId?: number);
|
304 | ```
|
305 |
|
306 | ##### Remove
|
307 |
|
308 | Remove and destroy a single toast by id
|
309 |
|
310 | ```
|
311 | toastrService.remove(toastId: number);
|
312 | ```
|
313 |
|
314 | ## SystemJS
|
315 |
|
316 | If you are using SystemJS, you should also adjust your configuration to point to
|
317 | the UMD bundle.
|
318 |
|
319 | In your SystemJS config file, `map` needs to tell the System loader where to
|
320 | look for `ngx-toastr`:
|
321 |
|
322 | ```js
|
323 | map: {
|
324 | 'ngx-toastr': 'node_modules/ngx-toastr/bundles/ngx-toastr.umd.min.js',
|
325 | }
|
326 | ```
|
327 |
|
328 | ## Setup Without Animations
|
329 |
|
330 | If you do not want to include `@angular/animations` in your project you can
|
331 | override the default toast component in the global config to use
|
332 | `ToastNoAnimation` instead of the default one.
|
333 |
|
334 | In your main module (ex: `app.module.ts`)
|
335 |
|
336 | ```typescript
|
337 | import { ToastrModule, ToastNoAnimation, ToastNoAnimationModule } from 'ngx-toastr';
|
338 |
|
339 | @NgModule({
|
340 | imports: [
|
341 | // ...
|
342 |
|
343 | // BrowserAnimationsModule no longer required
|
344 | ToastNoAnimationModule.forRoot(),
|
345 | ],
|
346 | // ...
|
347 | })
|
348 | class AppModule {}
|
349 | ```
|
350 |
|
351 | That's it! Animations are no longer required.
|
352 |
|
353 | ## Using A Custom Toast
|
354 |
|
355 | Create your toast component extending Toast see the demo's pink toast for an example
|
356 | https://github.com/scttcper/ngx-toastr/blob/master/src/app/pink.toast.ts
|
357 |
|
358 | ```typescript
|
359 | import { ToastrModule } from 'ngx-toastr';
|
360 |
|
361 | @NgModule({
|
362 | imports: [
|
363 | ToastrModule.forRoot({
|
364 | toastComponent: YourToastComponent, // added custom toast!
|
365 | }),
|
366 | ],
|
367 | entryComponents: [YourToastComponent], // add!
|
368 | bootstrap: [App],
|
369 | declarations: [App, YourToastComponent], // add!
|
370 | })
|
371 | class AppModule {}
|
372 | ```
|
373 |
|
374 | ## FAQ
|
375 |
|
376 | 1. ExpressionChangedAfterItHasBeenCheckedError: Expression has changed after it
|
377 | was checked\
|
378 | When opening a toast inside an angular lifecycle wrap it in setTimeout
|
379 |
|
380 | ```typescript
|
381 | ngOnInit() {
|
382 | setTimeout(() => this.toastr.success('sup'))
|
383 | }
|
384 | ```
|
385 |
|
386 | 2. Change default icons (check, warning sign, etc)\
|
387 | Overwrite the css background-image https://github.com/scttcper/ngx-toastr/blob/master/src/lib/toastr.css
|
388 | 3. How do I use this in an ErrorHandler? See:
|
389 | https://github.com/scttcper/ngx-toastr/issues/179
|
390 | 4. How can I translate messages See:
|
391 | https://github.com/scttcper/ngx-toastr/issues/201
|
392 | 5. How to handle toastr click/tap action?
|
393 |
|
394 | ```ts
|
395 | showToaster() {
|
396 | this.toastr.success('Hello world!', 'Toastr fun!')
|
397 | .onTap
|
398 | .pipe(take(1))
|
399 | .subscribe(() => this.toasterClickedHandler());
|
400 | }
|
401 |
|
402 | toasterClickedHandler() {
|
403 | console.log('Toastr clicked');
|
404 | }
|
405 | ```
|
406 |
|
407 | ## Previous Works
|
408 |
|
409 | [toastr](https://github.com/CodeSeven/toastr) original toastr\
|
410 | [angular-toastr](https://github.com/Foxandxss/angular-toastr) AngularJS toastr\
|
411 | [notyf](https://github.com/caroso1222/notyf) notyf (css)
|
412 |
|
413 | ## License
|
414 |
|
415 | MIT
|
416 |
|
417 | ---
|
418 |
|
419 | > GitHub [@scttcper](https://github.com/scttcper) ·
|
420 | > Twitter [@scttcper](https://twitter.com/scttcper)
|