Toast

Toast messages serve as a user-friendly means to communicate medium-priority events that users may wish to reference later. These messages appear temporarily on the screen and can be stored in a notifications panel until closed or expired.

Examples

Example 1: Setup Toast Container

To implement toast messages, import ToastContainerComponent from the clr-lift library and include <cll-toast-container [timeoutSeconds]="8" /> in your app component. This container will hold all toasts and should appear only once in your application. You can pass non-required inputs for global configurations, such as timeoutSeconds (auto close time), manualClosable (manual closure option), and topOffset (adjustment of distance to the screen top).

import {Component} from '@angular/core';
import {ToastContainerComponent} from 'clr-lift';

@Component({
  selector: 'app-root',
  imports: [ToastContainerComponent],
  template: `
    <clr-main-container>
      <!-- your app content -->
    </clr-main-container>

    <!-- toast container should appear only once -->
    <cll-toast-container [timeoutSeconds]="8" />
  `
})
export class AppComponent {}

Example 2: Create Toast with addToast

Use addToast to pass a toast object with required properties (title and description) and optional configurations.

import {ToastService} from 'clr-lift';
import {Component, inject} from '@angular/core';

@Component({})
export class ToastExampleComponent {
  private toastService = inject(ToastService);

  showToast() {
    this.toastService.addToast({
      // required properties
      title: 'Great Toast',
      description: 'I am a successful message!',

      // optional properties below
      toastType: 'success', // you can pass 'info', 'warning', 'error' as well
      date: '1hr ago',
      manualClosable: true,
      timeoutSeconds: 6,
      closed() {
        console.log('closed');
      },
      primaryButtonText: 'Primary Button',
      primaryButtonClick() {
        alert('primary button clicked');
      },
      secondaryButtonText: 'Secondary Button',
      secondaryButtonClick() {
        alert('secondary button clicked');
      },
    });
  }
}

Example 3: Shorthand APIs

For simplicity, four shorthand APIs are provided to create toasts with different types:

import {ToastService} from 'clr-lift';
import {Component, inject} from '@angular/core';

@Component({})
export class ToastShorthandExampleComponent {
  private toastService = inject(ToastService);

  showToasts() {
    this.toastService.success({
      title: 'Great Toast',
      description: 'I am a successful message!',
    });

    this.toastService.warning({
      title: 'Warning Toast',
      description: 'I am a warning message!',
    });

    this.toastService.error({
      title: 'Error Toast',
      description: 'I am a Error message! I will be closed in 10s automatically.',
      date: '1hr ago',
      timeoutSeconds: 10,
      primaryButtonText: 'More Info',
      primaryButtonClick() {
        alert('Assume opening a new tab');
      },
    });

    this.toastService.info({
      title: 'Info Toast',
      description: 'I am the default toast type.',
    });
  }
}

Usage Guidelines

Do:
  1. Provide Navigation: Include a link or location for users to navigate to from the toast.
  2. Use Relative Timestamps: Display timestamps relative to the user (e.g., "1 hour ago" instead of an absolute date).
  3. Keep Titles Short: Use a short, succinct title (max 35 characters) that conveys the high-level message quickly.
  4. Craft Consumable Descriptions: Keep descriptions concise (max 156 characters) for easy consumption.
Do Not:
  1. Use "Close" as an Action: Clicking the close button should close the toast.
  2. Overcrowd Actions: Limit toast messages to a maximum of 2 actions; prioritize the most important ones.
  3. Include Object Identifiers in Title: Avoid using object identifiers in the title; use them only in the description.
  4. Add Icons: To maintain clarity, refrain from adding icons to the toast messages.
  5. Show Irrelevant Toasts: Display toasts only when the information is still relevant to the user.

API Reference

ToastService

Service for creating and managing toast notifications.

Methods

  • addToast(options: ToastOptions): void

    Creates a toast with the specified options.

  • success(options: ToastOptions): void

    Creates a success toast with the specified options.

  • info(options: ToastOptions): void

    Creates an info toast with the specified options.

  • warning(options: ToastOptions): void

    Creates a warning toast with the specified options.

  • error(options: ToastOptions): void

    Creates an error toast with the specified options.

ToastOptions Interface

  • title: string

    (Required) The title of the toast message.

  • description: string

    (Required) The description of the toast message.

  • toastType?: 'success' | 'info' | 'warning' | 'error'

    (Optional) The type of toast. Defaults to 'info'.

  • date?: string

    (Optional) A relative timestamp (e.g., "1hr ago").

  • manualClosable?: boolean

    (Optional) Whether the toast can be manually closed. Defaults to true.

  • timeoutSeconds?: number

    (Optional) The number of seconds before the toast automatically closes. If not provided, uses the container's default.

  • primaryButtonText?: string

    (Optional) Text for the primary action button.

  • primaryButtonClick?: () => void

    (Optional) Callback function for the primary button click.

  • secondaryButtonText?: string

    (Optional) Text for the secondary action button.

  • secondaryButtonClick?: () => void

    (Optional) Callback function for the secondary button click.

  • closed?: () => void

    (Optional) Callback function called when the toast is closed.

ToastContainerComponent

Container component that holds all toast notifications. Should appear only once in your application.

Inputs

  • timeoutSeconds?: number

    (Optional) Default timeout in seconds for toasts. Defaults to 8 seconds.

  • manualClosable?: boolean

    (Optional) Whether toasts can be manually closed by default. Defaults to true.

  • topOffset?: number

    (Optional) Distance from the top of the screen in pixels. Defaults to 0.