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.

<button (click)="toast.show()">Show Toast</button>

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

To show a toast, call the show method on the ngpToast directive.

Reusable Component

Create a toast component that uses the NgpToast directive.

import { Component } from '@angular/core';
import { Toast } from './toast';

@Component({
  selector: 'app-root',
  imports: [Toast],
  template: `
    <button class="toast-trigger" (click)="toast.show()" ngpButton>Show Toast</button>

    <app-toast
      #toast
      header="This is a toast message"
      description="It will disappear in 3 seconds"
    />
  `,
  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 {}

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
ngpToastDuration
number
default: "3000"

The duration the toast will display for before it is automatically dismissed in milliseconds.

ngpToastGravity
NgpToastGravity
default: "'top'"

The direction the toast will appear from.

ngpToastPosition
NgpToastPosition
default: "'end'"

The position the toast will on the horizontal axis.

ngpToastStopOnHover
boolean
default: "true"

Whether the automatic dismissal of the toast should be paused when the user hovers over it.

ngpToastAriaLive
string
default: "'polite'"

Whether the toast should be announced to assistive technologies.

Data Attributes

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

Attribute Description Value
data-toast The visible state of the toast. visible | hidden
data-position The position of the toast. start | center | end
data-gravity The gravity of the toast. top | bottom

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({
      duration: 5000,
      position: 'center',
      gravity: 'top',
      stopOnHover: false,
      ariaLive: 'assertive',
      gap: 16,
    }),
  ],
});

NgpToastConfig

duration
number
default: "3000"

The duration in milliseconds that the toast will be visible.

position
start | center | end
default: "end"

The position of the toast.

gravity
top | bottom
default: "top"

The gravity of the toast. This will determine the location the toast will slide in and out.

stopOnHover
boolean
default: "true"

Whether the toast should stop the timer when hovered over. Once the mouse leaves the toast, the timer will restart.

ariaLive
assertive | polite
default: "polite"

The `aria-live` attribute value for the toast. This will determine how the toast will be read by screen readers.

gap
number
default: "16"

The gap between each toast.

Copyright © 2025 Angular Primitives