On this page
Toast
Headless, unstyled notifications stacked in a viewport. Add them with Toast.useToastManager(), or a Toast.createToastManager() instance outside React. They auto-dismiss on a timer that pauses while the viewport is hovered or focused, the window is blurred or the tab is hidden, queue beyond a limit, and announce themselves to screen readers. F6 moves focus to the newest toast and back.
Use for
- feedback for an action that has no surface of its own, such as a save after its form closed
- a loading, then success or error, notice for a promise
- a short confirmation beside the element that caused it, such as Copied
- showing a notification from outside React
Practices
| Guidance | Practice |
|---|---|
| Do | Render every toast from useToastManager().toasts, and filter anchored ones with Toast.isAnchored into a Toast.Positioner. |
| Do | Hide data-limited toasts with CSS. They stay in the list, inert, while queued. |
| Do | Use manager.promise() for an async action instead of adding and updating toasts by hand. It rethrows a rejection after showing the error toast, so catch it. |
| Do | Pass the same id to add to refresh an open toast. It bumps repeatCount and sets data-repeated. |
| Don’t | Use a toast for something the user must answer. Use Dialog, or useConfirmController for a confirm step. |
| Don’t | Render Toast.Arrow outside Toast.Positioner. It throws. |
API reference
Toast.Provider
Owns the toast list, timers and queue. Renders no element.
| Prop | Type | Description |
|---|---|---|
timeout | number | Auto-dismiss delay in ms. 0 keeps toasts until closed.Default: 5000 |
limit | number | Most stacked toasts shown at once. Older ones beyond it are marked limited.Default: 3 |
toastManager | ExternalToastManager | A manager from createToastManager(), for adding toasts outside React. |
Toast.Portal
Portals its children.
| Prop | Type | Description |
|---|---|---|
root | HTMLElement | null | RefObject<HTMLElement | null> | The element to portal into.Default: the `Portal` container |
Toast.Viewport
A div with role="region" and aria-label="Notifications" that holds the stack. Hover or focus inside pauses every timer. Carries data-expanded and --toast-frontmost-height.
Toast.Positioner
Places one toast against an anchor element, outside the stack and the limit. Carries data-side, data-align, data-anchor-hidden and the anchor CSS variables. Fields in toast.positionerProps override its props.
| Prop | Type | Description |
|---|---|---|
toast | ToastObject | The toast from useToastManager().toasts. |
anchor | Element | null | The element to sit next to.Default: null |
side | ToastSide | The side of the anchor. Flips when there is no room.Default: 'top' |
align | ToastAlign | Alignment along that side.Default: 'center' |
sideOffset | number | Gap to the anchor in px.Default: 0 |
alignOffset | number | Shift along the alignment axis in px.Default: 0 |
Toast.Root
One toast: a focusable div with role="dialog", labelled by its title and described by its description. Escape closes it. Carries data-type, data-expanded, data-limited, data-repeated, data-starting-style and data-ending-style, and --toast-index, --toast-offset-y, --toast-height and --toast-frontmost-height.
| Prop | Type | Description |
|---|---|---|
toast | ToastObject | The toast from useToastManager().toasts. |
Toast.Arrow
A FloatingArrow svg pointing at the anchor, inside Toast.Positioner. Carries data-side.
Toast.Content
A layout div. Carries data-behind on toasts behind the frontmost, and data-expanded.
Toast.Title
An h2 that labels the toast. Renders nothing without content.
| Prop | Type | Description |
|---|---|---|
children | React.ReactNode | The title.Default: toast.title |
Toast.Description
A p that describes the toast. Renders nothing without content.
| Prop | Type | Description |
|---|---|---|
children | React.ReactNode | The description.Default: toast.description |
Toast.Action
A button that merges toast.actionProps, runs its onClick, then closes the toast. Renders nothing without action props, children or render.
Toast.Close
A button that closes the toast.
Examples
Stacked toasts
function ToastList() {
const { toasts } = Toast.useToastManager();
return toasts.map(toast => (
<Toast.Root key={toast.id} toast={toast}>
<Toast.Content>
<Toast.Title />
<Toast.Description />
</Toast.Content>
<Toast.Action />
<Toast.Close aria-label='Close' />
</Toast.Root>
));
}
<Toast.Provider>
<App />
<Toast.Portal>
<Toast.Viewport>
<ToastList />
</Toast.Viewport>
</Toast.Portal>
</Toast.Provider>Promise
const manager = Toast.useToastManager();
manager
.promise(saveProfile(), {
loading: 'Saving…',
success: 'Profile saved',
error: 'Could not save',
})
.catch(() => {});