Toast API
import { showToast } from '@ambiki/impulse-view-components/toast';
const region = document.querySelector('awc-toast-region');
const toast = document.querySelector('awc-toast');showToast
Shows a toast in the page's toast region, built from a message or from a <template> holding a toast. A toast with the id of one already showing updates that one in place. Resolves with the <awc-toast> once it is showing, or with null, and a console warning, when the page has no region.
const toast = await showToast('Saved', { variant: 'success' });| Option | Description |
|---|---|
variant | 'info', 'success', 'warning' or 'danger'. Defaults to 'info'. |
title | A title, shown above the message. A toast from a template takes it only if the template's has a title. |
duration | How long, in milliseconds, the toast shows. Infinity keeps it until it is dismissed. |
id | The toast's id. Without one, the toast takes one of its own as it shows. |
The options are exported as ToastOptions.
showToast.promise
Shows a toast while a promise is pending, which stays until it settles, then updates it in place: a success toast once the promise resolves, or a danger toast once it rejects. Returns the promise; a rejection the caller ignores isn't reported as unhandled.
showToast.promise(createEvent(), {
loading: 'Creating event…',
success: (event) => `${event.name} created.`,
error: 'Could not create event.',
});| Option | Description |
|---|---|
loading | The message while the promise is pending. |
success | The message once it resolves, or a function of its value that returns one. |
error | The message once it rejects, or a function of the reason that returns one. |
title | A title, shown above the message at every step. |
id | The toast's id. Without one, each call gets its own toast. |
The options are exported as ToastPromiseOptions.
Region properties
placement
Where the toasts show: 'top-start', 'top-center', 'top-end', 'bottom-start', 'bottom-center' or 'bottom-end'. Defaults to 'top-center'.
region.placement = 'bottom-end';hotkey
The key that moves focus to the newest toast, and back to where it was. Defaults to 'F8'; empty turns it off. The region's aria-label, which names the key, doesn't change with it.
region.hotkey = 'F9';Toast properties
open
Whether the toast is showing. Setting it shows or hides the toast as show and hide do.
toast.open;
// => truevariant
'info', 'success', 'warning' or 'danger'. Defaults to 'info'.
toast.variant;
// => 'success'duration
How long, in milliseconds, the toast shows; Infinity keeps it until it is dismissed. Without a duration attribute, a danger toast and one holding an action stay until dismissed, and the others hide after 5000. Setting it while the toast is showing starts its timer over.
toast.duration;
// => 5000Toast methods
show
Shows the toast. Emits awc-toast:shown.
toast.show();hide
Hides the toast and removes it from the region. Emits awc-toast:hidden, but not the cancelable awc-toast:hide.
await toast.hide();requestShow
Shows the toast as if the user asked to. Emits a cancelable awc-toast:show, and does nothing if it is prevented.
toast.requestShow();requestHide
Hides the toast as if the user asked to. Emits a cancelable awc-toast:hide, and does nothing if it is prevented.
await toast.requestHide();Events
Events work as they do on native elements. The close button and Escape ask the toast to hide, emitting a cancelable hide first; calling preventDefault() on it keeps the toast. show(), hide(), changing open and the timer running out act directly, and emit no show or hide. shown and hidden fire after every show and hide, including the show of a toast rendered into the region, or added to it, once it connects. Updating a toast in place, and moving and removing it, emit nothing.
| Name | Bubbles | Cancelable | Description |
|---|---|---|---|
awc-toast:show | true | true | Fires before requestShow shows the toast. |
awc-toast:shown | true | false | Fires after the toast shows. |
awc-toast:hide | true | true | Fires before the user, or requestHide, hides it. |
awc-toast:hidden | true | false | Fires after the toast hides, before it is removed. |
document.addEventListener('awc-toast:hide', (event) => {
if (unsaved) event.preventDefault();
});