Toast
Show temporary status messages as a stack of notifications triggered from static methods.
Anatomy#
<Toast /> renders a portaled root with role="region" and aria-live="polite", holding one
list stack per placement and alignment. Each notification is an item. The icon reflects the
type. The actions row (holding cancel and action), close, and progress appear when the
matching option is set.
Usage#
Use Toast for temporary feedback that stays in the page. Use Alert Dialog when the next step should wait for an explicit choice.
Mount <Toast /> once. It holds no open state. Open notifications from event handlers with the
static methods.
Shared model#
Toast and Alert Dialog use the same options, actions, handle, and close
reasons. Every instance is created with a static method that takes an options object. Call options
override the host defaults, including false, 0, and null. A call before the host is mounted
throws. On the server the call returns a handle whose result() is already 'api'.
action.onClick and cancel.onClick run before the instance closes. A returned promise shows
loading on that button, disables the other one, and pauses the toast timer. A dialog also blocks
Escape, the overlay, and the corner close button. Calling event.preventDefault(), rejecting, or
throwing leaves the instance open. A throw or rejection is reported with console.error.
Otherwise the instance closes with 'action' or 'cancel'.
handle.close() and close(id) close with 'api'. Escape, the overlay, the corner close button,
and a swipe close with 'dismiss' and do not run the cancel handler. The timer closes with
'timeout'. result() resolves once with that reason, and calling it again returns the same
promise. The handle itself is not a promise.
update merges the next options into an open instance and restarts its timer. An update after close
does not reopen it. Reusing an open id in a new call updates that instance in place and returns
its existing handle. update replaces action and cancel as a whole, so include onClick again
when the label changes.
Custom content has two entry points. Toast.custom(render, options?) supplies a render for that
call. <Toast itemRender={render} /> supplies one for every other call on that host. A .custom()
render wins, then the host render, then the built-in layout. The render receives the id, the
resolved options, pending(), action(), cancel(), close(), update(), index, and
expanded. It replaces the inner content. The toast keeps its stack, swipe, timer, and live region.
close() closes with 'dismiss' unless you pass a reason.
A call without hostId goes to the host without an id and throws if only hosts with an id are
mounted. Pass hostId to target <Toast id="alerts" />.
Methods#
show is the neutral notice. info, success, warning, and error set the type. loading is
show with type: 'loading'. A loading toast never closes on its own because of that type. After
update changes the type, the normal duration applies again.
Action and dismissal#
action is the primary button. cancel: true uses the locale label, and cancel: { label } sets
one. The corner close button shows when closable is set on the call or the host. Loading toasts
hide the close button and the progress bar.
Large layout#
size="lg" moves the actions onto their own row and the close control to the top corner.
<Toast size="lg" /> applies that layout to every toast on the host.
Host options#
<Toast /> options set defaults for every toast on that host, and call options override them.
placement ('top' or 'bottom', default 'bottom') and align (default 'end') choose the
corner; each placement and alignment pair gets its own stack. type, size, variant, duration,
closable, progress, and preventDuplicate set per-toast defaults. maxVisible (default 3)
limits each stack, and later toasts stay queued until earlier ones close. A collapsed stack expands
while the pointer is over it; set expanded to keep it expanded. gap (default 14 px) sets the
spacing between toasts. translations overrides the viewport label and the close and cancel
labels.
Promises#
promise opens a loading toast and updates it when the promise settles. It accepts a promise or a
function that returns one. loading, success, and error are the same options object used
everywhere else. success and error may also be functions of the settled value or the rejection
reason. When either is omitted, that outcome closes the toast with 'api'. The method returns the
ordinary handle. Keep the original promise when you need the value.
Updates#
Toast.close(id) closes one toast, and Toast.close() without an id closes every toast.
Duplicates#
preventDuplicate compares the new toast with the front toast in the same host and corner. A match
bumps that toast, restarting its timer, and returns its handle. The option is a boolean on the host
or on the call. It does not apply to a call that sets id.
Duration and progress#
duration defaults to 4000 milliseconds, and Infinity keeps the toast open until dismissed.
progress shows the remaining-time bar. The timer pauses while the pointer is over the stack, the
window is blurred or the tab is hidden, a swipe is in progress, or an action promise is pending.
Custom content#
Examples#
Archive an item with undo#
The action button restores the conversation with another toast.
Track an asynchronous deployment#
promise swaps the loading toast for the success or error options.
Report distinct task outcomes#
The type methods set the icon and the live-region role. An error toast uses alert. The others
use status.
Deduplicate rapid user actions#
preventDuplicate keeps a repeated click on the front toast.
Route notifications to a custom viewport corner#
hostId sends the toast to <Toast id="bottom-dock" />. Toast.close() dismisses every toast.
Show upload progress#
.custom() draws the progress row. The toast shell still owns stacking, swipe, and the timer.
duration: Infinity keeps this one open until it is dismissed.
API Reference#
Attributes#
data-behinddata-bumpdata-closeddata-expandeddata-frontdata-limiteddata-swipe-outdata-swipingProps#
Props for the Toast host component. Renders a <section> element by default.