Primitives

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.

import { Component, inject } from '@angular/core';
import { NgpToastManager } from 'ng-primitives/toast';
import { Toast } from './toast';

@Component({
  selector: 'app-root',
  template: `
    <button class="toast-trigger" (click)="show()" ngpButton>Show Toast</button>
  `,
  styles: `
    .toast-trigger {
      padding-left: 1rem;
      padding-right: 1rem;
      border-radius: 0.5rem;
      color: var(--ngp-text-primary);
      border: none;
      outline: none;
      height: 2.5rem;
      font-weight: 500;
      background-color: var(--ngp-background);
      transition: background-color 300ms cubic-bezier(0.4, 0, 0.2, 1);
      box-shadow: var(--ngp-button-shadow);
    }

    .toast-trigger[data-hover] {
      background-color: var(--ngp-background-hover);
    }

    .toast-trigger[data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 2px;
    }

    .toast-trigger[data-press] {
      background-color: var(--ngp-background-active);
    }
  `,
})
export default class App {
  private readonly toastManager = inject(NgpToastManager);

  show(): void {
    this.toastManager.show(Toast, {
      context: {
        header: 'Toast Title',
        description: 'This is a description of the toast notification.',
      },
    });
  }
}

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.

API Reference

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

NgpToast

  • Selector: [ngpToast]
  • Exported As: 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-width The width of the toast in pixels.
--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,
      width: 300,
      offsetTop: 16,
      offsetBottom: 16,
      offsetLeft: 16,
      offsetRight: 16,
      dismissible: true,
      maxToasts: 3,
      zIndex: 9999999,
      swipeDirections: ['left', 'right'],
      ariaLive: 'assertive',
      gap: 16,
    }),
  ],
});

NgpToastConfig

placement
NgpToastPlacement
default: "top-end"

The default placement of the toast. Can be one of `top-start`, `top-end`, `top-center`, `bottom-start`, `bottom-end`, or `bottom-center`.

duration
number
default: "3000"

The duration in milliseconds that the toast will be visible.

width
number
default: "360"

The width of each toast in pixels.

offsetTop
number
default: "24"

The offset from the top of the viewport in pixels.

offsetBottom
number
default: "24"

The offset from the bottom of the viewport in pixels.

offsetLeft
number
default: "24"

The offset from the left of the viewport in pixels.

offsetRight
number
default: "24"

The offset from the right of the viewport in pixels.

dismissible
boolean
default: "true"

Whether a toast can be dismissed by swiping.

swipeThreshold
number
default: "45"

The amount a toast must be swiped before it is considered dismissed.

swipeDirections
NgpToastSwipeDirection[]
default: "['left', 'right', 'top', 'bottom']"

The default swipe directions supported by the toast.

maxToasts
number
default: "3"

The maximum number of toasts that can be displayed at once.

ariaLive
string
default: "'polite'"

The aria live setting.

gap
number
default: "14"

The gap between each toast.

zIndex
number
default: "9999999"

The z-index of the toast container.

Copyright © 2025 Angular Primitives