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.

Pass sequential: true when calling show, or set it globally via provideToastConfig to make it the default for every toast.

Persistent Toasts

Persistent toasts do not auto-dismiss. They remain visible until the user dismisses them (by swiping when dismissible is enabled) or until they are dismissed programmatically — either via the returned NgpToastRef or via the manager (toastManager.toasts() + toastManager.dismiss()). This is useful for notification centers and other surfaces where messages must stay until acknowledged.

Pass persistent: true when calling show, or set it globally via provideToastConfig to make it the default for every toast.

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,
      persistent: false,
    }),
  ],
});

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.