Web component

<p-toasts>

A stack of toast notifications

Import
@parallelogram-js/core/components/PToasts
Tag
p-toasts

Playground

Toast stack

The buttons use the Toast component to show toasts in this stack.

<p-toasts placement="bottom-right"></p-toasts>

<div class="button-row">
  <button type="button" data-toast-trigger="success" data-toast-message="Table booked for 7pm">Success</button>
  <button type="button" data-toast-trigger="warning" data-toast-message="Only two tables left tonight">Warning</button>
  <button type="button" data-toast-trigger="error" data-toast-message="Payment was declined" data-toast-title="Booking not saved">Error</button>
</div>

About

Toasts are announced through two live regions that exist from the moment the element is created: info and success messages politely, warnings and errors straight away. Toasts close after a timeout, except errors, which stay until dismissed, and every timer waits while the pointer or keyboard focus is on the stack.

Where popovers are supported the element shows itself as a manual popover and moves to the top of the top layer with each new toast. While a <p-modal> or modal <dialog> is open, the element moves inside it to show a toast, because everything outside an open modal is inert, and returns to its place when the modal closes, or with the next toast when the modal was removed without closing.

Without JavaScript

This element renders nothing of its own, so before the module loads there is no stack and toast() is not there to call. Nothing on the page is lost, since a toast is something the page asks for rather than content it already had. A message the server already knows about is better rendered as ordinary HTML, which needs no script at all.

Usage

Register the component and the framework loads it the first time a page contains p-toasts.

import { Parallelogram } from '@parallelogram-js/core';

const app = Parallelogram.create();
app.components.add('p-toasts', () => import('@parallelogram-js/core/components/PToasts'));
app.run();

Attributes

NameTypeDefaultDescription
dismiss-labelstringDismiss notificationThe accessible name of the dismiss button on each toast For every instance, PToasts.defaults.dismissLabel.
placementtop-right | top-left | top-center | bottom-right | bottom-left | bottom-centertop-rightWhere the stack sits on the screen

Methods

NameSignatureDescription
toast(options: { message: string; type?: 'info' | 'success' | 'warning' | 'error' | 'warn' | 'danger'; title?: string; timeout?: number; dismissible?: boolean; allowHTML?: boolean }) => () => voidShow a toast and return a function that closes it; timeout is in milliseconds, or 0 to keep it, and allowHTML treats the message as trusted HTML, inserted through the parallelogram Trusted Types policy

Events

NameDetailDescription
p-toasts:show{ id: number; type: string; message: string }A toast was shown; bubbles out of shadow roots DOM event
p-toasts:close{ id: number; type: string; message: string }A toast closed; bubbles out of shadow roots DOM event

Shadow parts

NameDescription
stackThe element holding the toasts
toastEach toast
titleA toast's title
closeA toast's dismiss button

CSS custom properties

NameDefaultDescription
--toast-bg-infovar(--color-inverse-surface)Background of info toasts
--toast-bg-successvar(--color-success)Background of success toasts
--toast-bg-warningvar(--color-warning)Background of warning toasts
--toast-bg-errorvar(--color-danger)Background of error toasts
--toast-text-colornoneText colour of every toast; defaults to --color-inverse-text on info toasts and to the status colour’s -contrast on the others
--toast-border-radiusnoneCorner radius
--toast-shadow0 6px 20px rgba(0, 0, 0, 0.25), inset 0 0 0 1px var(--color-border)Shadow, including the inset ring that edges the toast
--toast-paddingnoneSpace around the stack
--toast-gapnoneSpace between toasts
--toast-item-paddingnonePadding inside each toast
--toast-min-width300pxNarrowest a toast gets
--toast-max-width500pxWidest a toast gets
--toast-fontnoneFont shorthand
--toast-animation-durationnoneLength of the enter and leave animations
--toast-z-indexnoneStacking order where popovers aren't supported