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.
• componentSuffix: The suffix to apply to the generated component class name.
• fileSuffix: The suffix to apply to the generated component file name. Defaults to component.
• exampleStyles: 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

Data Attributes

The following data attributes are applied to the first child of the ngpToast ng-template:

Attribute	Description	Value
data-position-x	The horizontal position of the toast	start, center, end
data-position-y	The vertical position of the toast	top, bottom
data-visible	Whether the toast is currently visible. This is based on how many toasts are shown compared to the maxToasts set in the global config.	true, false
data-front	Whether the toast is the front-most toast in the stack.	true, false
data-swiping	Whether the toast is currently being swiped.	true, false
data-swipe-direction	The direction of the swipe gesture.	left, right, up, down
data-expanded	Whether the toast is currently expanded. This can be used to collapse or expand stacked toasts.	true, false

The following CSS custom properties are available to the ngpToast directive:

Property	Description
--ngp-toast-gap	The gap between each toast.
--ngp-toast-z-index	The z-index of the toast.
--ngp-toasts-before	The number of toasts before this one.
--ngp-toast-index	The index of the toast (1-based).
--ngp-toast-height	The height of the toast in pixels.
--ngp-toast-offset	The vertical offset position of the toast.
--ngp-toast-front-height	The height of the front-most toast.
--ngp-toast-swipe-amount-x	The swipe amount on the X axis (pixel value).
--ngp-toast-swipe-amount-y	The swipe amount on the Y axis (pixel value).
--ngp-toast-swipe-x	The swipe value on the X axis.
--ngp-toast-swipe-y	The swipe value on the Y axis.

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

The default placement of the toast. Can be one of `top-start`, `top-end`, `top-center`, `bottom-start`, `bottom-end`, or `bottom-center`. The duration in milliseconds that the toast will be visible. The offset from the top of the viewport in pixels. The offset from the bottom of the viewport in pixels. The offset from the left of the viewport in pixels. The offset from the right of the viewport in pixels. Whether a toast can be dismissed by swiping. The amount a toast must be swiped before it is considered dismissed. The default swipe directions supported by the toast. The maximum number of toasts that can be displayed at once. The aria live setting. The gap between each toast. The z-index of the toast container. When enabled, only the front toast's timer will run. When a toast is dismissed, the timer will start on the next toast. Useful for scenarios with multiple notifications where you want to prevent background toasts from auto-closing.