Toast Notification

Global Toaster

1. Create a single toaster instance in a shared file and export it for use throughout your app.

import {createToaster} from "@qualcomm-ui/react/toast"

export const globalToaster = createToaster({
  overlap: true,
  position: "bottom-end",
})

2. Import and render the simple Toaster component near the root of your application.

// shared/toaster.ts
import {Toaster} from "@qualcomm-ui/react/toast"

import {globalToaster} from "./shared"

function AppRoot() {
  return (
    <>
      <Toaster toaster={globalToaster} />
      {/* ...the rest of your app */}
    </>
  )
}

Alternatively, you can provide children to the Toaster component to customize the rendering of the toasts. If children are omitted, the default toast rendering is used.

// <Toaster /> is ultimately a shortcut for this:
<Toaster toaster={toaster}>
  {(toast) => {
    return (
      <Toast.Root key={toast.id}>
        <Toast.Heading>{toast.title}</Toast.Heading>
        <Toast.Description>{toast.description}</Toast.Description>
        <Toast.CloseButton />
      </Toast.Root>
    )
  }}
</Toaster>

With Action

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

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

Toast Emphasis

Here's an example of each toast type.

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 toaster.create function.

const toaster = createToaster({
  overlap: true,
  placement: "bottom-end",
})

Toast Duration

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

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.

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.

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.

const toaster = createToaster({
  max: 3,
  placement: "bottom-end",
})

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.

const topToaster = createToaster({
  placement: "top-end",
})

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

ToastCreateOptions

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

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

boolean

true

| string
| ReactElement

number

string

| string
| ReactElement

Record<
  string,
  any
>

(
  details: ToastStatusChangeDetails,
) => void

number

200

| 'success'
| 'danger'
| 'loading'
| 'info'
| 'warning'
| 'neutral'

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

boolean

| string
| ReactElement

number

string

| string
| ReactElement

Record<
  string,
  any
>

(
  details: ToastStatusChangeDetails,
) => void

number

| 'success'
| 'danger'
| 'loading'
| 'info'
| 'warning'
| 'neutral'

ToasterCreateOptions

Options passed to the createToaster function.

number

number

16

number

12

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

"1rem"

boolean

false

boolean

true

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

"bottom-end"

number

200

number

number

number

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

boolean

boolean

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

number

ToasterInstance

This is the instance returned from the createToaster function.

ToasterCreateOptions

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

(
  id?: string,
) => void

() => number

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

(
  id: string,
) => boolean

(
  id: string,
) => boolean

(
  id?: string,
) => void

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

(
  id?: string,
) => void

(
  id?: string,
) => void

(
  subscriber: (
    ...args: any[]
  ) => void,
) => VoidFunction

(
  id: string,
  data: Partial<
    ToastApiProps<V>
  >,
) => string

ToasterCreateOptions

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

(
  id?: string,
) => void

() => number

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

(
  id: string,
) => boolean

(
  id: string,
) => boolean

(
  id?: string,
) => void

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

(
  id?: string,
) => void

(
  id?: string,
) => void

(
  subscriber: (
    ...args: any[]
  ) => void,
) => VoidFunction

(
  id: string,
  data: Partial<
    ToastApiProps<V>
  >,
) => string

<Toaster>

ToasterInstance

FunctionRenderProp<ToastOptions>

'ltr' | 'rtl'

'ltr'

() =>
| Node
| ShadowRoot
| Document

| ReactElement
| ((
    props: object,
  ) => ReactElement)

ToasterInstance

FunctionRenderProp<ToastOptions>

'ltr' | 'rtl'

() =>
| Node
| ShadowRoot
| Document

| ReactElement
| ((
    props: object,
  ) => ReactElement)

ToastPromiseOptions

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

Omit<
  ToastOptions,
  'type'
>

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

() => void | Promise<void>

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

Omit<
  ToastOptions,
  'type'
>

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

() => void | Promise<void>

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

ToastStatusChangeDetails

string

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

string

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