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 {Toast, Toaster, createToaster} from "@qualcomm-ui/react/toast"Usage Guidelines
Global Toaster
- 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",
})- Import and render the simple
Toastercomponent 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>Examples
Demos
Each demo uses its own <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.
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.
import type {ReactElement} from "react"
import type {QdsNotificationEmphasis} from "@qualcomm-ui/qds-core/inline-notification"
import {Button} from "@qualcomm-ui/react/button"
import {createToaster, Toaster} from "@qualcomm-ui/react/toast"
const toaster = createToaster({
placement: "bottom-end",
})
const types: QdsNotificationEmphasis[] = [
"info",
"success",
"warning",
"danger",
"neutral",
"loading",
]
export function ToastEmphasisDemo(): ReactElement {
return (
<>
<div className="flex flex-wrap gap-4">
{types.map((emphasis) => (
<Button
key={emphasis}
onClick={() =>
toaster.create({
label: `The status is ${emphasis}`,
type: emphasis,
})
}
variant="outline"
>
{emphasis}
</Button>
))}
</div>
<Toaster toaster={toaster} />
</>
)
}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.
import {type ReactElement, useState} from "react"
import {Button} from "@qualcomm-ui/react/button"
import {createToaster, Toaster} from "@qualcomm-ui/react/toast"
const toaster = createToaster({
placement: "bottom-end",
})
export function ToastPauseDemo(): ReactElement {
const [paused, setPaused] = useState(false)
const [shown, setShown] = useState(false)
const show = () => {
toaster.create({
label: "This is a success toast",
onStatusChange: (details) => {
if (details.status === "visible") {
setShown(true)
} else if (details.status === "dismissing") {
setShown(false)
}
},
type: "success",
})
}
const pause = () => {
toaster.pause()
setPaused(true)
}
const play = () => {
toaster.resume()
setPaused(false)
}
return (
<>
<Toaster toaster={toaster} />
<div className="flex gap-4">
<Button disabled={shown} onClick={show} variant="outline">
Show Toast
</Button>
<Button disabled={!shown || paused} onClick={pause} variant="outline">
Pause Toast
</Button>
<Button disabled={!shown || !paused} onClick={play} variant="outline">
Play Toast
</Button>
</div>
</>
)
}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",
})
API
In the following sections, the toaster instance is referred to as toaster.
ToastCreateOptions
These are the options passed to the toaster.createToast function.
{
label: string
onClick: () => void
}
boolean| string
| ReactElement
numberstring| string
| ReactElement
Record<
string,
any
>
(
details: ToastStatusChangeDetails,
) => void
number| 'success'
| 'danger'
| 'loading'
| 'info'
| 'warning'
| 'neutral'
ToasterCreateOptions
Options passed to the createToaster function.
numbernumbernumber| string
| Record<
| 'bottom'
| 'left'
| 'right'
| 'top',
string
>
booleanboolean| 'top-start'
| 'top'
| 'top-end'
| 'bottom-start'
| 'bottom'
| 'bottom-end'
numberToasterInstance
This is the instance returned from the createToaster function.
(
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>
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'
>