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

Use our provideToaster function to create a toaster instance near the root of your application.
Inject the ToasterService.
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>

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.

Brand

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

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

@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.

Brand

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.

Brand

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.

Brand

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.

Brand

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.

Brand

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.

Brand

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.

Brand

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.

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

action

Type

{
  label: string
  onClick: () => void
}

Description

The action of the toast

closable

Type

boolean

Description

Whether the toast is closable

description

Type

string

Description

The description of the toast.

duration

Type

number

Description

The duration the toast will be visible, in milliseconds.

Type

string

Description

The unique id of the toast

label

Type

string

Description

The title of the toast.

ToasterCreateOptions

Options passed to the createToaster / provideToaster functions.

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

duration

Type

number

Description

The duration the toast will be visible, in milliseconds. By default, this is determined by the type of the toast.

gap

Type

number

Description

The gap between the toasts

max

Type

number

Description

The maximum number of toasts. When the number of toasts exceeds this limit, the new toasts are queued.

offsets

Type

| string
| Record<
    | 'bottom'
    | 'left'
    | 'right'
    | 'top',
    string
  >

Description

The offset from the safe environment edge of the viewport

overlap

Type

boolean

Description

Whether to overlap the toasts

pauseOnPageIdle

Type

boolean

Description

Whether to pause toast when the user leaves the browser tab

placement

Type

| 'top-start'
| 'top'
| 'top-end'
| 'bottom-start'
| 'bottom'
| 'bottom-end'

Description

The placement of the toast

removeDelay

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.

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

attrs

Type

ToasterCreateOptions

Description

The attributes of the toast store

create

Type

(
  data: ToastOptions<string>,
) => string

Description

Create a new toast with the given options

dismiss

Type

(
  id?: string,
) => void

Description

Dismiss a toast by its ID. If no ID is provided, dismisses all toasts

getCount

Type

() => number

Description

Get the total number of toasts

getVisibleToasts

Type

() => Partial<
  ToastApiProps<string>
>[]

Description

Get all currently visible toasts

isDismissed

Type

(
  id: string,
) => boolean

Description

Check if a toast with the given ID has been dismissed

isVisible

Type

(
  id: string,
) => boolean

Description

Check if a toast with the given ID is currently visible

pause

Type

(
  id?: string,
) => void

Description

Pause a toast's auto-dismiss timer. If no ID is provided, pauses all toasts

promise

Type

(
  promise:
    | Promise<T>
    | (() => Promise<T>),
  options: ToastPromiseOptions<string>,
  shared?: Omit<
    ToastOptions<V>,
    'type'
  >,
) => {
  id: string
  unwrap: () => Promise<T>
}

Description

Create a toast that tracks a promise's state

remove

Type

(
  id?: string,
) => void

Description

Remove a toast by its ID

resume

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

update

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.

Prop	Type
loading ^* The options for the toast that displays while the Promise is pending.	Omit< ToastOptions, 'type' >
error The function called when the Promise is rejected.	( response: any, ) => Omit< ToastOptions<V>, 'type' >
finally The function called after the Promise is resolved successfully or rejected.	() => void \| Promise<void>
success The function called when the Promise is resolved successfully.	( response: any, ) => Omit< ToastOptions<V>, 'type' >

Type

Omit<
  ToastOptions,
  'type'
>

Description

The options for the toast that displays while the Promise is pending.

error

Type

(
  response: any,
) => Omit<
  ToastOptions<V>,
  'type'
>

Description

The function called when the Promise is rejected.

finally

Type

() => void | Promise<void>

Description

The function called after the Promise is resolved successfully or rejected.

success

Type

(
  response: any,
) => Omit<
  ToastOptions<V>,
  'type'
>

Description

The function called when the Promise is resolved successfully.

ToastStatusChangeDetails

Prop	Type
src The reason for the status change	string
status The render status of the toast	\| 'visible' \| 'dismissing' \| 'unmounted'

src

Type

string

Description

The reason for the status change

status

Type

| 'visible'
| 'dismissing'
| 'unmounted'

Description

The render status of the toast

Progress Ring