Skip to content

Toast API ​

js
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.

js
const toast = await showToast('Saved', { variant: 'success' });
OptionDescription
variant'info', 'success', 'warning' or 'danger'. Defaults to 'info'.
titleA title, shown above the message. A toast from a template takes it only if the template's has a title.
durationHow long, in milliseconds, the toast shows. Infinity keeps it until it is dismissed.
idThe 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.

js
showToast.promise(createEvent(), {
  loading: 'Creating event…',
  success: (event) => `${event.name} created.`,
  error: 'Could not create event.',
});
OptionDescription
loadingThe message while the promise is pending.
successThe message once it resolves, or a function of its value that returns one.
errorThe message once it rejects, or a function of the reason that returns one.
titleA title, shown above the message at every step.
idThe 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'.

js
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.

js
region.hotkey = 'F9';

Toast properties ​

open ​

Whether the toast is showing. Setting it shows or hides the toast as show and hide do.

js
toast.open;
// => true

variant ​

'info', 'success', 'warning' or 'danger'. Defaults to 'info'.

js
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.

js
toast.duration;
// => 5000

Toast methods ​

show ​

Shows the toast. Emits awc-toast:shown.

js
toast.show();

hide ​

Hides the toast and removes it from the region. Emits awc-toast:hidden, but not the cancelable awc-toast:hide.

js
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.

js
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.

js
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.

NameBubblesCancelableDescription
awc-toast:showtruetrueFires before requestShow shows the toast.
awc-toast:showntruefalseFires after the toast shows.
awc-toast:hidetruetrueFires before the user, or requestHide, hides it.
awc-toast:hiddentruefalseFires after the toast hides, before it is removed.
js
document.addEventListener('awc-toast:hide', (event) => {
  if (unsaved) event.preventDefault();
});

Released under the MIT License.