Toast

A toast is a non-modal, unobtrusive window element used to display brief, auto-expiring messages to the user.

Import

Import the Toast primitives from ng-primitives/toast.

import { NgpToast } from 'ng-primitives/toast';

Usage

Assemble the toast directives in your template.

<ng-template #toast>
  <div ngpToast>...</div>
</ng-template>

To show a toast, inject the NgpToastManager service and call the show method passing the toast template or a component class that uses the NgpToast directive as a Host Directive.

import { NgpToastManager } from 'ng-primitives/toast';

export class MyComponent {
  private readonly toastManager = inject(NgpToastManager);

  showToast(): void {
    this.toastManager.show(toastTemplate);
    // or
    this.toastManager.show(MyToastComponent);
  }
}

Reusable Component

Create a toast component that uses the NgpToast directive.

Schematics

Generate a reusable toast component using the Angular CLI.

ng g ng-primitives:primitive toast

Options

• path: The path at which to create the component file.
• prefix: The prefix to apply to the generated component selector.
• component-suffix: The suffix to apply to the generated component class name.
• file-suffix: The suffix to apply to the generated component file name. Defaults to component.
• example-styles: Whether to include example styles in the generated component file. Defaults to true.

Examples

Here are some additional examples of how to use the Toast primitive.

Sequential Mode

The sequential mode prevents background toasts from auto-closing. Only the front-most toast's timer runs, and when that toast is dismissed, the timer starts on the next toast in the stack.

This is useful when you have multiple notifications in quick succession (e.g., health monitoring of external services) where you want to ensure users can see all notifications before they auto-close.

You can enable sequential mode in two ways:

1. Globally via configuration:

import { provideToastConfig } from 'ng-primitives/toast';

bootstrapApplication(AppComponent, {
  providers: [
    provideToastConfig({
      sequential: true,
      // ... other config options
    }),
  ],
});

2. Per-toast via the show method:

import { NgpToastManager } from 'ng-primitives/toast';

export class MyComponent {
  private readonly toastManager = inject(NgpToastManager);

  showToast(): void {
    this.toastManager.show(ToastComponent, {
      sequential: true,
    });
  }
}

API Reference

The following directives are available to import from the ng-primitives/toast package:

NgpToast

Global Configuration

You can configure the default options for all toasts in your application by using the provideToastConfig function in a providers array.

import { provideToastConfig } from 'ng-primitives/toast';

bootstrapApplication(AppComponent, {
  providers: [
    provideToastConfig({
      placement: 'top-end',
      duration: 5000,
      offsetTop: 16,
      offsetBottom: 16,
      offsetLeft: 16,
      offsetRight: 16,
      dismissible: true,
      maxToasts: 3,
      zIndex: 9999999,
      swipeDirections: ['left', 'right'],
      ariaLive: 'assertive',
      gap: 16,
    }),
  ],
});

NgpToastConfig

Accessibility

For screen reader announcements, ensure your toast container includes role="status" or role="alert" with aria-live="polite" so that new toasts are announced to assistive technology users.