Skip to main content
Toast renders one notification. Your application controls when it appears, its position, and when it is removed.

Usage

Visual options

Compare neutral, success, error, information, and warning feedback with the same message and progress. For application notifications, wrap the application in ToastProvider, mount a Toaster inside it, and use useToast() from descendants. Each provider owns an independent notification store, countdowns, and dismissal lifecycle. Multiple Toasters can mirror the same provider.

Application notifications

enqueueToast accepts Toast props and an optional dedupeKey, and returns the notification ID. A matching visible key returns the existing ID without adding another notification. updateToast({ id, ...changes }) patches that live notification. closeToast(id) dismisses one notification; closeToast() dismisses all visible notifications in the provider. The provider defaults to three visible notifications. limit must be a positive integer and can change while the provider is mounted. Lowering it or adding above it dismisses the oldest visible notifications first. Increasing it leaves existing notifications unchanged and does not restore dismissed notifications. Configuration changes preserve the store, surviving IDs, order, and remaining countdown time.

Provider lifecycle

Multiple Toasters inside a provider render the same notifications. Updates and dismissal apply to every mirror, and each notification has one shared countdown. Hover or focus inside any mirror pauses it; it resumes after all mirrors release both. Mounting another Toaster does not restart the countdown or create another callback lifecycle. Use separate providers for independent queues. For provider notifications, expiry, the close button, closeToast, and limit eviction call the latest onClose once. The notification is already dismissed when the callback runs, so updates and repeated close requests for that ID have no effect. onCancel remains a separate action callback and does not dismiss automatically. Dismissed notifications are inert during exit animations. Their entries are removed after all rendered mirrors finish their exit work or unmount. Unmounting the last Toaster clears dismissed entries and freezes the remaining time for visible notifications. Remounting a Toaster resumes that time. Unmounting the provider discards its notifications and cancels countdown and exit work without calling onClose. Captured enqueueToast, updateToast, and closeToast operations from that provider have no effect after it unmounts. getToastProps adapts each notification’s content and presentation. Set duration and progress in enqueueToast or updateToast so every mirror shares the same timing configuration. Existing timing overrides through getToastProps remain supported when all mirrors return the same duration and progress for a notification. The provider retains the ID, dismissal handler, and shared countdown. container selects a Toaster’s portal destination. When omitted, it uses the surrounding theme container or document.body. An explicit element renders there; null defers rendering. Visible notifications remain queued, with their countdowns paused while no Toaster is rendered. Portals retain the surrounding theme and direction. Set aria-label on each Toaster to localize its default region name, “Notifications”, and give mirrored regions appropriate names.

Update a live notification

Use the ID returned by enqueueToast to update content, feedback status, actions, or callbacks in place. Updates preserve the notification’s ID and position. Unknown or dismissed IDs have no effect, including while the dismissal animation runs. Each useToast() call targets its closest provider.
ToastUpdate requires id and accepts partial Toast options. Omitted fields keep their current values. Explicit undefined clears an optional field or restores its component default, such as progress: undefined or status: undefined. Pass null to remove a content slot, including description, icon, or action. Setting cancelLabel: null hides the cancel control while preserving its callback. Callback changes take effect on the existing notification. dedupeKey belongs to enqueueing and cannot be updated.

Dismissal timing

The countdown defaults to 6,000 milliseconds. It pauses while the pointer is over the toast or keyboard focus is inside it, and resumes only after both leave. With multiple Toasters, pause state is shared across their mirrors. The visual countdown follows the remaining dismissal time. Automatic dismissal also works when reduced motion disables the animation. For example, updateToast({ id, children: 'Still saving' }) preserves the remaining time, while updateToast({ id, duration: 6000 }) gives the reader another six seconds. These rules apply to the existing notification without changing its ID or position.

Dismissible notification

onClose is called once by the close button or when the countdown completes. Remove the toast in that callback. Use duration={0} for a notification that stays open until dismissal.

Progress and cancellation

Passing progress supplies a percentage and disables the countdown. Remove it after the operation finishes to start a fresh duration. Cancellation invokes onCancel; the parent owns cancellation and removal. cancelLabel accepts a React node for the button content. Children, description, icon, and action also accept caller-owned React nodes. Use Twenty UI controls for interactive actions and provide their accessible names.

Appearance and announcements

status accepts neutral, info, success, warning, or error and defaults to neutral. It expresses feedback meaning and selects the icon and theme palette. Toast has one supported appearance, so it exposes no appearance variant or palette color option. Use icon to replace the icon, icon={null} to omit it, and iconLabel when the default icon needs its own accessible name. The default role is status with polite announcements. Use role="alert" for urgent feedback. Set cancelLabel and closeLabel to localize the controls, and allow enough time to read the content or interact with its actions.

Props

The reference is generated from the public component types. Native attributes, styles, class names, event handlers, and refs target the root. Use render to compose another element or component while retaining those props and the ref. Toaster portals inherit the surrounding theme and text direction.
ReactNode
Optional footer node, such as a Button with a caller-owned action.
ReactNode
default:"Cancel"
Cancel button content node. Defaults to Cancel. Pass null to hide the control.
ReactNode
Main message node. Callers own its content and accessible text.
string
Additional class names merged onto the root.
string
default:"Close"
Accessible name of the close button. Defaults to Close.
ReactNode
Optional supporting content node rendered below the message.
number
default:"6000"
Milliseconds before onClose is called, defaulting to 6000. Zero keeps the toast open. Changes restart the countdown; live updateToast duration patches restart it even when unchanged. Hover and keyboard focus pause it until both leave.
ReactNode
Leading icon node. Defaults to the status icon. Pass null to omit it.
string
Accessible name of the default icon. Without it, the icon is decorative.
(() => void)
Called when the cancel button is clicked. Providing it and renderable cancelLabel content shows the button.
(() => void)
For standalone Toast, called once per mount by the close button or expiry. For provider notifications, called once on close, expiry, closeToast, or limit eviction, after dismissal and before exit cleanup. Provider teardown does not call it.
number
Completion percentage. Providing it disables the countdown. Removing it starts a fresh duration.
Ref<HTMLDivElement>
Ref to the root div, or the element supplied through render.
RenderProp<Record<string, unknown>>
Element or callback composition for the root. Native props and the ref target the rendered element.
"error" | "info" | "neutral" | "success" | "warning"
default:"neutral"
Feedback meaning: neutral, info, success, warning, or error. Defaults to neutral and selects the icon and theme palette.
CSSProperties
Inline styles forwarded to the root.

ToastProvider

ReactNode
Application content and any Toasters sharing this provider’s independent notification store and lifecycle.
number
default:"3"
Reactive maximum number of visible toasts, defaulting to three. Must be a positive integer. Lowering it or adding above it dismisses the oldest visible notifications and calls their onClose once. Surviving IDs, order, and countdowns are preserved.

Toaster

Native div attributes, styles, class names, and refs target the notification region.
HTMLElement | null
Portal destination. Omit to use the theme container or document.body; null defers rendering. The provider retains visible notifications and pauses their countdowns while no Toaster is rendered.
((toast: ToastNotification) => Partial<Omit<ToastProps, "ref" | "id" | "onClose">>)
Adapts notification content and presentation. The provider owns id, dismissal, and the shared countdown. Set timing through enqueueToast or updateToast; duration and progress overrides must match across Toasters sharing a provider.
RenderProp<Record<string, unknown>>
Custom root element composed through Base UI.