Toast Notification

Toasts display temporary, high-visibility messages that appear briefly in the viewport to communicate system events or status changes without interrupting user interactions.

import {ToastModule, createToaster} from "@qualcomm-ui/angular/toast"

Usage Guidelines

Global Toaster

  1. Use our provideToaster function to create a toaster instance near the root of your application.
  2. Inject the ToasterService.
  3. Import and render the q-toaster directive with the ToasterService.toaster property.
import {Component} from "@angular/core"
import {provideToaster, ToasterService} from "@qualcomm-ui/angular/toast"

@Component({
  providers: [provideToaster({placement: "bottom-end"})],
  template: `
    <div q-toaster [toaster]="toaster"></div>
    <!-- the rest of your app... -->
  `,
})
export class AppComponent {
  protected readonly toaster = inject(ToasterService).toaster
}

To customize toast rendering, you can provide an <ng-template> child element to the q-toaster directive. If children are omitted, a fallback element will be used instead.

<div q-toaster [toaster]="toaster">
  <!-- typesafe toast object is available via the q-toast-context directive -->
  <ng-template q-toast-context let-toast>
    <div q-toast-root>
      <h3 q-toast-label>{{ toast.title }}</h3>
      <p q-toast-description>{{ toast.description }}</p>
      <button q-toast-close-button></button>
    </div>
  </ng-template>
</div>

Examples

Demos

Each demo uses its own q-toaster instance for demonstration. Note that multiple toaster instances may obscure other toasts in practice, so it's recommended to use a single toaster instance for your entire app.

With Action

Use the action property to add an action button to the toast.

import {Component, inject} from "@angular/core"

import {WINDOW} from "@qualcomm-ui/angular-core/dom"
import {ButtonModule} from "@qualcomm-ui/angular/button"
import {
  provideToaster,
  ToasterService,
  ToastModule,
} from "@qualcomm-ui/angular/toast"

@Component({
  imports: [ToastModule, ButtonModule],
  providers: [provideToaster({placement: "bottom-end"})],
  selector: "toast-action-demo",
  template: `
    <div q-toaster [toaster]="toaster"></div>

    <button q-button variant="outline" (click)="createToast()">
      Create Toast
    </button>
  `,
})
export class ToastActionDemo {
  toaster = inject(ToasterService).toaster

  protected readonly window = inject(WINDOW)

  createToast() {
    this.toaster.create({
      action: {
        label: "Action",
        onClick: () => {
          this.window.alert("You clicked an action")
        },
      },
      description: "Toast Description",
      label: "Toast Label",
    })
  }
}

Toast Emphasis

Here's an example of each toast type.

import {Component, inject} from "@angular/core"

import {ButtonModule} from "@qualcomm-ui/angular/button"
import {
  provideToaster,
  ToasterService,
  ToastModule,
} from "@qualcomm-ui/angular/toast"
import type {QdsNotificationEmphasis} from "@qualcomm-ui/qds-core/inline-notification"

@Component({
  imports: [ToastModule, ButtonModule],
  providers: [provideToaster({placement: "bottom-end"})],
  selector: "toast-emphasis-demo",
  template: `
    <div q-toaster [toaster]="toaster"></div>

    <div class="flex flex-wrap gap-4">
      @for (emphasis of types; track emphasis) {
        <button q-button variant="outline" (click)="createToast(emphasis)">
          {{ emphasis }}
        </button>
      }
    </div>
  `,
})
export class ToastEmphasisDemo {
  toaster = inject(ToasterService).toaster

  protected readonly types: QdsNotificationEmphasis[] = [
    "info",
    "success",
    "warning",
    "danger",
    "neutral",
    "loading",
  ]

  createToast(emphasis: QdsNotificationEmphasis) {
    this.toaster.create({
      label: `The status is ${emphasis}`,
      type: emphasis,
    })
  }
}

Overlapping Toasts

By default, toasts are stacked on top of each other. To conserve space when rendering many toasts, set the overlap property to true in the createToaster function.

import {Component, inject} from "@angular/core"

import {ButtonModule} from "@qualcomm-ui/angular/button"
import {
  provideToaster,
  ToasterService,
  ToastModule,
} from "@qualcomm-ui/angular/toast"

@Component({
  imports: [ToastModule, ButtonModule],
  providers: [
    provideToaster({
      overlap: true,
      placement: "bottom-end",
    }),
  ],
  selector: "toast-overlap-demo",
  template: `
    <div q-toaster [toaster]="toaster"></div>

    <button q-button variant="outline" (click)="createToast()">
      Show Toast
    </button>
  `,
})
export class ToastOverlapDemo {
  toaster = inject(ToasterService).toaster

  createToast() {
    this.toaster.create({
      description: "Toast Description",
      label: "Toast Label",
    })
  }
}

Toast Duration

Use the duration property to set the duration of the toast.

import {Component, inject} from "@angular/core"

import {ButtonModule} from "@qualcomm-ui/angular/button"
import {
  provideToaster,
  ToasterService,
  ToastModule,
} from "@qualcomm-ui/angular/toast"

@Component({
  imports: [ToastModule, ButtonModule],
  providers: [provideToaster({overlap: true, placement: "bottom-end"})],
  selector: "toast-duration-demo",
  template: `
    <div q-toaster [toaster]="toaster"></div>

    <button q-button variant="outline" (click)="createToast()">
      Show Toast
    </button>
  `,
})
export class ToastDurationDemo {
  protected readonly toaster = inject(ToasterService).toaster

  createToast() {
    this.toaster.create({
      duration: 10000,
      label: "Task failed successfully",
      type: "success",
    })
  }
}

Persistent Toast

Set the type property to loading to make the toast stay on screen until dismissed.

import {Component, inject} from "@angular/core"

import {ButtonModule} from "@qualcomm-ui/angular/button"
import {
  provideToaster,
  ToasterService,
  ToastModule,
} from "@qualcomm-ui/angular/toast"

@Component({
  imports: [ToastModule, ButtonModule],
  providers: [
    provideToaster({
      overlap: true,
      placement: "bottom-end",
    }),
  ],
  selector: "toast-persistent-demo",
  template: `
    <div q-toaster [toaster]="toaster"></div>

    <button q-button variant="outline" (click)="createToast()">
      Show Toast
    </button>
  `,
})
export class ToastPersistentDemo {
  toaster = inject(ToasterService).toaster

  createToast() {
    this.toaster.create({
      label: "Persistent Toast",
      type: "loading",
    })
  }
}

Pause and Resume

Use the pause and resume methods on the toaster instance to pause and play the toast.

Pausing a toast prevents it from timing out, while resuming it will continue the timeout from the remaining duration.

import {Component, inject, signal} from "@angular/core"

import {ButtonModule} from "@qualcomm-ui/angular/button"
import {
  provideToaster,
  ToasterService,
  ToastModule,
} from "@qualcomm-ui/angular/toast"

@Component({
  imports: [ToastModule, ButtonModule],
  providers: [provideToaster({placement: "bottom-end"})],
  selector: "toast-pause-demo",
  template: `
    <div q-toaster [toaster]="toaster"></div>

    <div class="flex gap-4">
      <button q-button variant="outline" [disabled]="shown()" (click)="show()">
        Show Toast
      </button>
      <button
        q-button
        variant="outline"
        [disabled]="!shown() || paused()"
        (click)="pause()"
      >
        Pause Toast
      </button>
      <button
        q-button
        variant="outline"
        [disabled]="!shown() || !paused()"
        (click)="play()"
      >
        Play Toast
      </button>
    </div>
  `,
})
export class ToastPauseDemo {
  toaster = inject(ToasterService).toaster

  protected readonly paused = signal(false)
  protected readonly shown = signal(false)

  show() {
    this.toaster.create({
      label: "This is a success toast",
      onStatusChange: (details) => {
        if (details.status === "visible") {
          this.shown.set(true)
        } else if (details.status === "dismissing") {
          this.shown.set(false)
        }
      },
      type: "success",
    })
  }

  pause() {
    this.toaster.pause()
    this.paused.set(true)
  }

  play() {
    this.toaster.resume()
    this.paused.set(false)
  }
}

Max Visible

Set the max prop on the createToaster function to define the maximum number of toasts that can be rendered at a time. Extra toasts will be queued and rendered when the number of visible toasts drops below the max.

import {Component, inject} from "@angular/core"

import {ButtonModule} from "@qualcomm-ui/angular/button"
import {
  provideToaster,
  ToasterService,
  ToastModule,
} from "@qualcomm-ui/angular/toast"

@Component({
  imports: [ToastModule, ButtonModule],
  providers: [
    provideToaster({
      max: 3,
      placement: "bottom-end",
    }),
  ],
  selector: "toast-max-visible-demo",
  template: `
    <div q-toaster [toaster]="toaster"></div>

    <button q-button variant="outline" (click)="createToast()">
      Show Toast
    </button>
  `,
})
export class ToastMaxVisibleDemo {
  toaster = inject(ToasterService).toaster

  createToast() {
    this.toaster.create({
      description: "Toast Description",
      label: "Toast Label",
    })
  }
}

Screen Placement

Toasts can be displayed on all four corners of a page. We recommend picking a single placement for your app, as this creates a consistent experience for your users.

import {Component} from "@angular/core"

import {ButtonModule} from "@qualcomm-ui/angular/button"
import {createToaster, ToastModule} from "@qualcomm-ui/angular/toast"

@Component({
  imports: [ToastModule, ButtonModule],
  selector: "toast-placement-demo",
  template: `
    <div q-toaster [toaster]="topToaster"></div>
    <div q-toaster [toaster]="bottomToaster"></div>

    <div class="flex gap-4">
      <button q-button variant="outline" (click)="showTop()">
        Show Top Toast
      </button>

      <button q-button variant="outline" (click)="showBottom()">
        Show Bottom Toast
      </button>
    </div>
  `,
})
export class ToastPlacementDemo {
  topToaster = createToaster({
    placement: "top-end",
  })

  bottomToaster = createToaster({
    placement: "bottom-start",
  })

  showTop() {
    this.topToaster.create({
      description: "Toast Description",
      label: "Toast Label",
    })
  }

  showBottom() {
    this.bottomToaster.create({
      description: "Toast Description",
      label: "Toast Label",
    })
  }
}

API

In the following sections, the toaster instance is referred to as toaster.

ToastCreateOptions

These are the options passed to the toaster.create function.

PropTypeDefault
The action of the toast
{
label: string
onClick: () => void
}
Whether the toast is closable
boolean
true
The description of the toast.
string
The duration the toast will be visible, in milliseconds.
number
The unique id of the toast
string
The title of the toast.
string
The metadata of the toast. Use this to provide additional information about the toast for use in your own component
Record<
string,
any
>
Function called when the toast is visible
| ((
details: ToastStatusChangeDetails,
) => void)
| undefined
The duration the toast will be visible, in milliseconds. Required for exit transitions.
number
200
The type of the toast. Controls the color and icon of the toast.
| 'success'
| 'danger'
| 'loading'
| 'info'
| 'warning'
| 'neutral'
Type
{
label: string
onClick: () => void
}
Description
The action of the toast
Type
boolean
Description
Whether the toast is closable
Type
string
Description
The description of the toast.
Type
number
Description
The duration the toast will be visible, in milliseconds.
Type
string
Description
The unique id of the toast
Type
string
Description
The title of the toast.
Type
Record<
string,
any
>
Description
The metadata of the toast. Use this to provide additional information about the toast for use in your own component
Type
| ((
details: ToastStatusChangeDetails,
) => void)
| undefined
Description
Function called when the toast is visible
Type
number
Description
The duration the toast will be visible, in milliseconds. Required for exit transitions.
Type
| 'success'
| 'danger'
| 'loading'
| 'info'
| 'warning'
| 'neutral'
Description
The type of the toast. Controls the color and icon of the toast.

ToasterCreateOptions

Options passed to the createToaster / provideToaster functions.

PropTypeDefault
The duration the toast will be visible, in milliseconds. By default, this is determined by the type of the toast.
number
The gap between the toasts
number
16
The maximum number of toasts. When the number of toasts exceeds this limit, the new toasts are queued.
number
12
The offset from the safe environment edge of the viewport
| string
| Record<
| 'bottom'
| 'left'
| 'right'
| 'top',
string
>
"1rem"
Whether to overlap the toasts
boolean
false
Whether to pause toast when the user leaves the browser tab
boolean
true
The placement of the toast
| 'top-start'
| 'top'
| 'top-end'
| 'bottom-start'
| 'bottom'
| 'bottom-end'
"bottom-end"
The duration for the toast to kept alive before it is removed. Useful for exit transitions.
number
200
Type
number
Description
The duration the toast will be visible, in milliseconds. By default, this is determined by the type of the toast.
Type
number
Description
The gap between the toasts
Type
number
Description
The maximum number of toasts. When the number of toasts exceeds this limit, the new toasts are queued.
Type
| string
| Record<
| 'bottom'
| 'left'
| 'right'
| 'top',
string
>
Description
The offset from the safe environment edge of the viewport
Type
boolean
Description
Whether to overlap the toasts
Type
boolean
Description
Whether to pause toast when the user leaves the browser tab
Type
| 'top-start'
| 'top'
| 'top-end'
| 'bottom-start'
| 'bottom'
| 'bottom-end'
Description
The placement of the toast
Type
number
Description
The duration for the toast to kept alive before it is removed. Useful for exit transitions.

ToasterInstance

This is the instance returned from the createToaster function.

PropType
The attributes of the toast store
Create a new toast with the given options
    (
    data: ToastOptions<V>,
    ) => string
    Dismiss a toast by its ID. If no ID is provided, dismisses all toasts
      (
      id?: string,
      ) => void
      Get the total number of toasts
        () => number
        Get all currently visible toasts
          () => Partial<
          ToastApiProps<V>
          >[]
          Check if a toast with the given ID has been dismissed
            (
            id: string,
            ) => boolean
            Check if a toast with the given ID is currently visible
              (
              id: string,
              ) => boolean
              Pause a toast's auto-dismiss timer. If no ID is provided, pauses all toasts
                (
                id?: string,
                ) => void
                Create a toast that tracks a promise's state
                  <T>(
                  promise:
                  | Promise<T>
                  | (() => Promise<T>),
                  options: ToastPromiseOptions<V>,
                  shared?: Omit<
                  ToastOptions<V>,
                  'type'
                  >,
                  ) =>
                  | {
                  id: string | undefined
                  unwrap: () => Promise<T>
                  }
                  | undefined
                  Remove a toast by its ID
                    (
                    id?: string,
                    ) => void
                    Resume a toast's auto-dismiss timer. If no ID is provided, resumes all toasts
                      (
                      id?: string,
                      ) => void
                      Subscribe to the toast store
                        (
                        subscriber: (
                        ...args: any[]
                        ) => void,
                        ) => VoidFunction
                        Update an existing toast with new properties
                          (
                          id: string,
                          data: Partial<
                          ToastApiProps<V>
                          >,
                          ) => string
                          Description
                          The attributes of the toast store
                          Type
                          (
                          data: ToastOptions<V>,
                          ) => string
                          Description
                          Create a new toast with the given options
                            Type
                            (
                            id?: string,
                            ) => void
                            Description
                            Dismiss a toast by its ID. If no ID is provided, dismisses all toasts
                              Type
                              () => number
                              Description
                              Get the total number of toasts
                                Type
                                () => Partial<
                                ToastApiProps<V>
                                >[]
                                Description
                                Get all currently visible toasts
                                  Type
                                  (
                                  id: string,
                                  ) => boolean
                                  Description
                                  Check if a toast with the given ID has been dismissed
                                    Type
                                    (
                                    id: string,
                                    ) => boolean
                                    Description
                                    Check if a toast with the given ID is currently visible
                                      Type
                                      (
                                      id?: string,
                                      ) => void
                                      Description
                                      Pause a toast's auto-dismiss timer. If no ID is provided, pauses all toasts
                                        Type
                                        <T>(
                                        promise:
                                        | Promise<T>
                                        | (() => Promise<T>),
                                        options: ToastPromiseOptions<V>,
                                        shared?: Omit<
                                        ToastOptions<V>,
                                        'type'
                                        >,
                                        ) =>
                                        | {
                                        id: string | undefined
                                        unwrap: () => Promise<T>
                                        }
                                        | undefined
                                        Description
                                        Create a toast that tracks a promise's state
                                          Type
                                          (
                                          id?: string,
                                          ) => void
                                          Description
                                          Remove a toast by its ID
                                            Type
                                            (
                                            id?: string,
                                            ) => void
                                            Description
                                            Resume a toast's auto-dismiss timer. If no ID is provided, resumes all toasts
                                              Type
                                              (
                                              subscriber: (
                                              ...args: any[]
                                              ) => void,
                                              ) => VoidFunction
                                              Description
                                              Subscribe to the toast store
                                                Type
                                                (
                                                id: string,
                                                data: Partial<
                                                ToastApiProps<V>
                                                >,
                                                ) => string
                                                Description
                                                Update an existing toast with new properties

                                                  ToastPromiseOptions

                                                  These are the options passed to the toaster.promise function.

                                                  PropType
                                                  The options for the toast that displays while the Promise is pending.
                                                  Omit<
                                                  ToastOptions<V>,
                                                  'type'
                                                  >
                                                  The function called when the Promise is rejected.
                                                    | ((
                                                    response: any,
                                                    ) => Omit<
                                                    ToastOptions<V>,
                                                    'type'
                                                    >)
                                                    | undefined
                                                    The function called after the Promise is resolved successfully or rejected.
                                                      () => void | Promise<void>
                                                      The function called when the Promise is resolved successfully.
                                                        | ((
                                                        response: any,
                                                        ) => Omit<
                                                        ToastOptions<V>,
                                                        'type'
                                                        >)
                                                        | undefined
                                                        Type
                                                        Omit<
                                                        ToastOptions<V>,
                                                        'type'
                                                        >
                                                        Description
                                                        The options for the toast that displays while the Promise is pending.
                                                        Type
                                                        | ((
                                                        response: any,
                                                        ) => Omit<
                                                        ToastOptions<V>,
                                                        'type'
                                                        >)
                                                        | undefined
                                                        Description
                                                        The function called when the Promise is rejected.
                                                          Type
                                                          () => void | Promise<void>
                                                          Description
                                                          The function called after the Promise is resolved successfully or rejected.
                                                            Type
                                                            | ((
                                                            response: any,
                                                            ) => Omit<
                                                            ToastOptions<V>,
                                                            'type'
                                                            >)
                                                            | undefined
                                                            Description
                                                            The function called when the Promise is resolved successfully.

                                                              ToastStatusChangeDetails

                                                              PropType
                                                              The reason for the status change
                                                              string
                                                              The render status of the toast
                                                              | 'visible'
                                                              | 'dismissing'
                                                              | 'unmounted'
                                                              Type
                                                              string
                                                              Description
                                                              The reason for the status change
                                                              Type
                                                              | 'visible'
                                                              | 'dismissing'
                                                              | 'unmounted'
                                                              Description
                                                              The render status of the toast
                                                              Updated by Olaf Kappes