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>
Use the example to see the events it sends.
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
| Name | Type | Default | Description |
|---|---|---|---|
dismiss-label | string | Dismiss notification | The accessible name of the dismiss button on each toast For every instance, PToasts.defaults.dismissLabel. |
placement | top-right | top-left | top-center | bottom-right | bottom-left | bottom-center | top-right | Where the stack sits on the screen |
Methods
| Name | Signature | Description |
|---|---|---|
toast | (options: { message: string; type?: 'info' | 'success' | 'warning' | 'error' | 'warn' | 'danger'; title?: string; timeout?: number; dismissible?: boolean; allowHTML?: boolean }) => () => void | Show 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
| Name | Detail | Description |
|---|---|---|
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
| Name | Description |
|---|---|
stack | The element holding the toasts |
toast | Each toast |
title | A toast's title |
close | A toast's dismiss button |
CSS custom properties
| Name | Default | Description |
|---|---|---|
--toast-bg-info | var(--color-inverse-surface) | Background of info toasts |
--toast-bg-success | var(--color-success) | Background of success toasts |
--toast-bg-warning | var(--color-warning) | Background of warning toasts |
--toast-bg-error | var(--color-danger) | Background of error toasts |
--toast-text-color | none | Text colour of every toast; defaults to --color-inverse-text on info toasts and to the status colour’s -contrast on the others |
--toast-border-radius | none | Corner radius |
--toast-shadow | 0 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-padding | none | Space around the stack |
--toast-gap | none | Space between toasts |
--toast-item-padding | none | Padding inside each toast |
--toast-min-width | 300px | Narrowest a toast gets |
--toast-max-width | 500px | Widest a toast gets |
--toast-font | none | Font shorthand |
--toast-animation-duration | none | Length of the enter and leave animations |
--toast-z-index | none | Stacking order where popovers aren't supported |