Work in progress - do not use in production. This component is still being built: it is not flagged Ready for Dev, so its markup, attributes, events and styles can all still change without notice, it is not covered by the accessibility gate, and it is not published to npm. It is on this site so the work can be seen and reviewed - nothing more.

Toast

A transient notification, overlaid on the page and docked to a corner. Built on the native <output> element, which is its own live region: <output is="root-toast">.

Usage

A toast is raised by a button, through the platform's invoker commands - no script of your own. The toast is authored hidden; command="--toast-show" shows it.

<button is="root-button" type="button" data-variant="primary" data-color="default" command="--toast-show" commandfor="toast-saved">
  Save
</button>

<output is="root-toast" id="toast-saved" variant="success" hidden>Message saved</output>

Where the element is written says nothing about where it appears: on show it moves into a fixed container docked to a corner of the viewport, above the page. A toast that is not hidden when it connects shows itself immediately.

The element is its own ARIA live region. The message is inserted on the frame after the toast connects, so assistive tech observes a mutation against an already-connected region rather than a pre-populated one.

Types

One button per type, one toast per type:

<button is="root-button" type="button" data-variant="primary" data-color="default" command="--toast-show" commandfor="toast-info">Info</button>
<button is="root-button" type="button" data-variant="primary" data-color="default" command="--toast-show" commandfor="toast-success">Success</button>
<button is="root-button" type="button" data-variant="primary" data-color="default" command="--toast-show" commandfor="toast-warning">Warning</button>
<button is="root-button" type="button" data-variant="primary" data-color="danger" command="--toast-show" commandfor="toast-danger">Danger</button>

<output is="root-toast" id="toast-info" variant="info" hidden>Info - something worth knowing</output>
<output is="root-toast" id="toast-success" variant="success" hidden>Success - that worked</output>
<output is="root-toast" id="toast-warning" variant="warning" hidden>Warning - check this before continuing</output>
<output is="root-toast" id="toast-danger" variant="danger" hidden>Danger - that did not work</output>

How long it stays

The variant decides, because reading time does. An authored auto-dismiss always wins, and auto-dismiss="none" (or "0") keeps a toast up until it is dismissed.

Variant	Auto-dismiss	Close button
`success`	3000ms	opt-in
`info`	4000ms	opt-in
`warning`	6000ms	opt-in
`danger`	never	by default

An error that disappears on its own is an error nobody saw: danger waits, and gets the close button to wait with. no-dismiss takes that button back off it.

Docking

dock names the corner - logical, so the sides follow the writing mode. The newest toast is always the one nearest that corner, and the stack grows away from it.

<button is="root-button" type="button" data-variant="secondary" data-color="default" command="--toast-show" commandfor="toast-top-start">Top start</button>
<button is="root-button" type="button" data-variant="secondary" data-color="default" command="--toast-show" commandfor="toast-top-end">Top end</button>
<button is="root-button" type="button" data-variant="secondary" data-color="default" command="--toast-show" commandfor="toast-bottom-start">Bottom start</button>
<button is="root-button" type="button" data-variant="secondary" data-color="default" command="--toast-show" commandfor="toast-bottom-end">Bottom end</button>

<output is="root-toast" id="toast-top-start" dock="top-start" hidden>Docked top start</output>
<output is="root-toast" id="toast-top-end" dock="top-end" hidden>Docked top end</output>
<output is="root-toast" id="toast-bottom-start" dock="bottom-start" hidden>Docked bottom start</output>
<output is="root-toast" id="toast-bottom-end" dock="bottom-end" hidden>Docked bottom end (the default)</output>

Attributes

Attribute	Type	Default	Description
`variant`	`'info' \| 'success' \| 'warning' \| 'danger'`	`'info'`	Tone, and how long the toast stays
`dock`	`'top-start' \| 'top-end' \| 'bottom-start' \| 'bottom-end'`	`'bottom-end'`	Which corner it overlays
`auto-dismiss`	`number \| 'none'`	from `variant`	Override the delay in ms; `none` / `0` for never
`dismissible`	`boolean`	`danger` only	Inject a close button (`button[dismiss]`, `aria-label="Close"`)
`no-dismiss`	`boolean`	`false`	Take the close button off a `danger` toast
`assertive`	`boolean`	`false`	Use `role="alert"` (assertive) instead of `role="status"` (polite)
`stacked`	`boolean`	`false`	Lay the message and the close button in a column
`hidden`	`boolean`	-	Authored on a toast that waits for its command

Events

Event	Detail	Description
`root-toast.dismiss`	-	Fired when the toast is dismissed (button, auto-dismiss, or `dismiss()`)

Methods

Method	Description
`show()`	Dock the toast, unhide it and start its delay; restarts the delay if it is already up
`dismiss()`	Hide the toast, clear the delay and emit `root-toast.dismiss`

Extends

HTMLOutputElement - use with <output is="root-toast">.