A React toast stack with a Liquid Glass style, actions, promise states, and four corner positions.
ToastProvider supplies the toast manager. Render Toast inside it to draw the portal, viewport, and Liquid Glass stack; call useToast() anywhere inside the provider to add, update, close, or track notifications.
Render one ToastProvider near the app root and place Toast after your app content. Each provider owns a separate viewport, so pass the same toastManager to it when you also create toasts outside React.
add queues a toast with a title, description, and optional type. Toasts dismiss after timeout (5000 ms by default), and the timer pauses while the viewport is hovered or focused.
type selects a built-in status icon: info, success, warning, error, or loading. Unknown types still render, just without an icon. Use priority: "high" for an assertive announcement.
loading is rendered automatically by toast.promise, so it is usually not created directly.
actionProps renders an action button inside the toast. The action forwards children and native button props; close the toast yourself from onClick when the action is complete.
Nothing archived yet.
toast.promise starts with a loading toast and updates the same toast to success or error when the promise settles.
The toast updates when the promise resolves.
position anchors the stack to a corner: top-left, top-right, bottom-left, or bottom-right. Toasts stack away from the nearest vertical edge, and swipe dismissal follows the anchored corner.
Current position: bottom-right
update replaces fields on an existing toast, and close removes one toast or every toast when no ID is passed. The example keeps the ID returned by add so it can advance a loading toast to success.
No upload in progress.
ToastProvider accepts limit and timeout. A timeout of 0 keeps toasts open until your code or the user closes them. The example keeps a two-toast stack that never auto-dismisses.
createToastManager creates a manager that any module can call. Pass the instance to ToastProvider through toastManager so the viewport renders the toasts it creates.
The viewport is a live region. High-priority toasts use an alertdialog role and the rest use a dialog role; titles and descriptions are connected with aria-labelledby and aria-describedby.
The stack supports F6 focus entry plus swipe dismissal, and timers pause while the viewport is hovered or focused. When you replace the default close button, give your close control an accessible name. See the accessibility guide for announcement guidance.
ToastProvider
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | — | App content that can call useToast(). |
timeout | number | 5000 | Default auto-dismiss delay in milliseconds; 0 keeps toasts open. |
limit | number | 3 | Maximum number of visible toasts. Older toasts stay mounted with data-limited. |
toastManager | ToastManager | — | Global manager created with createToastManager. |
Toast
| Prop | Type | Default | Description |
|---|---|---|---|
position | "top-left" | "top-right" | "bottom-left" | "bottom-right" | "bottom-right" | Corner where the stack is anchored. |
close | ReactNode | Built-in close button | Custom content rendered in place of the default close button. |
className | string | — | Tailwind classes merged into each toast. |
style | CSSProperties | — | Inline styles merged into the same element as className. |
ui | { viewport?: ClassValue; root?: ClassValue; glass?: ClassValue; overlay?: ClassValue; content?: ClassValue; icon?: ClassValue; text?: ClassValue; title?: ClassValue; description?: ClassValue; actions?: ClassValue; action?: ClassValue; close?: ClassValue } | — | Tailwind classes for internal slots, keyed by data-slot. |
render | ReactElement | ((props, state) => ReactElement) | — | Replaces each toast root element. |
ref | Ref<HTMLDivElement> | — | Ref forwarded to each toast root. |
useToast
| Method | Description |
|---|---|
add(options) | Adds a toast and returns its ID. |
update(id, options) | Updates an existing toast. |
close(id?) | Closes one toast, or every toast when id is omitted. |
promise(promise, options) | Tracks a promise with loading, success, and error options. |
toasts | The current toast objects. |
Toast options
add accepts these fields. update accepts ToastUpdateOptions, a partial version without id, and promise uses the same update options for its loading, success, and error states. Below, ToastOptions means the add options and ToastUpdateOptions means Partial<Omit<ToastOptions, "id">>.
| Option | Type | Default | Description |
|---|---|---|---|
id | string | generated | Stable identifier for add. Adding an existing ID updates that toast in place; update and promise do not accept id. |
title | ReactNode | — | Toast heading. |
description | ReactNode | — | Supporting copy under the title. |
type | string | — | Status icon: info, success, warning, error, or loading. |
timeout | number | 5000 | Auto-dismiss delay in milliseconds; 0 keeps the toast open. |
priority | "low" | "high" | "low" | Polite or assertive announcement. |
actionProps | ComponentPropsWithoutRef<"button"> | — | Action button props, including children and onClick. |
onClose | () => void | — | Called when the toast closes. |
onRemove | () => void | — | Called after the toast is removed from the list. |
data | object | — | Custom payload attached to the toast object. |
Promise options
| Option | Type | Default | Description |
|---|---|---|---|
loading | string | ToastUpdateOptions | — | Toast shown while the promise is pending. |
success | string | ToastUpdateOptions | ((value) => string | ToastUpdateOptions) | — | Toast shown when the promise resolves. |
error | string | ToastUpdateOptions | ((error) => string | ToastUpdateOptions) | — | Toast shown when the promise rejects. |
createToastManager
createToastManager() returns a manager with the same add, update, close, and promise methods as useToast(). It does not expose the current toasts list; read that with useToast() inside React. Use the manager when code outside React needs to create toasts, and pass the instance to ToastProvider through toastManager.
Toast attributes
| Attribute | Description |
|---|---|
data-expanded | Present when the toast is expanded in the viewport. |
data-limited | Present when the toast was limited because the limit was exceeded. |
data-type | Indicates the toast type (info, success, warning, error, or loading). |
data-swiping | Present while the toast is being swiped. |
data-swipe-direction | Indicates the swipe direction (up, down, left, or right). |
data-starting-style | Present when the toast begins animating in. |
data-ending-style | Present when the toast is animating out. |
data-behind | Present when the toast is behind the frontmost toast in the stack. |
data-position | Indicates the anchored corner on the viewport. |
data-icon | Indicates the status icon type on the icon slot. |
data-slot | Marks internal parts (viewport, root, glass, overlay, content, icon, text, title, description, actions, action, close) for styling. |
The glass surface, stack geometry, and motion are shared across slots. Use ui.root, ui.glass, ui.overlay, and ui.content for per-slot styling; ui.viewport positions the stack, while className and style merge into each toast root. Prefer the shared --ui-glass-* tokens for material changes.