Toast

<zeno-toast>FeedbackSource

A short message that appears over the page and goes away by itself.

import '@usezeno/tokens/css';
import '@usezeno/core/web-components';

Examples

Variants

A toast renders nothing until show() is called. It then closes by itself after duration milliseconds, 5000 by default. The toast is fixed to the browser window, so it appears at the edge of the window and not inside this example.

Default Info Success Warning Error

<zeno-button variant="outline">Default</zeno-button>
<zeno-button variant="outline">Info</zeno-button>
<zeno-button variant="outline">Success</zeno-button>
<zeno-button variant="outline">Warning</zeno-button>
<zeno-button variant="outline">Error</zeno-button>
<zeno-toast title="Report" message="The weekly report is ready."></zeno-toast>

const toast = document.querySelector('zeno-toast');
const variants = ['default', 'info', 'success', 'warning', 'error'];
document.querySelectorAll('zeno-button').forEach((button, index) => {
  button.addEventListener('click', () => {
    toast.variant = variants[index];
    toast.show();
  });
});

Light style and icon

light uses a light background with a coloured border. icon names an icon from the icon registry.

Save

<zeno-button>Save</zeno-button>
<zeno-toast light variant="success" icon="check" title="Saved" message="Your changes are saved."></zeno-toast>

document.querySelector('zeno-button').addEventListener('click', () => {
  document.querySelector('zeno-toast').show();
});

Positions

position chooses the edge or corner of the window.

Top start Top Top end Bottom start Bottom Bottom end

<zeno-button variant="outline">Top start</zeno-button>
<zeno-button variant="outline">Top</zeno-button>
<zeno-button variant="outline">Top end</zeno-button>
<zeno-button variant="outline">Bottom start</zeno-button>
<zeno-button variant="outline">Bottom</zeno-button>
<zeno-button variant="outline">Bottom end</zeno-button>
<zeno-toast duration="2000" message="The link is copied."></zeno-toast>

const toast = document.querySelector('zeno-toast');
const positions = ['top-start', 'top', 'top-end', 'bottom-start', 'bottom', 'bottom-end'];
document.querySelectorAll('zeno-button').forEach((button, index) => {
  button.addEventListener('click', () => {
    toast.position = positions[index];
    toast.show();
  });
});

Stays open, with an action

With duration="0" the toast stays until it is closed. The text can come from the default slot, and the action slot holds a button. The close button sends a close event.

Delete the file

The file is in the list.

The file was deleted. Undo

<zeno-button>Delete the file</zeno-button>
<p data-result>The file is in the list.</p>
<zeno-toast duration="0" position="bottom-end">
  The file was deleted.
  <zeno-button slot="action" size="sm">Undo</zeno-button>
</zeno-toast>

const toast = document.querySelector('zeno-toast');
const result = document.querySelector('[data-result]');
const buttons = document.querySelectorAll('zeno-button');
buttons[0].addEventListener('click', () => {
  result.textContent = 'The file is deleted.';
  toast.show();
});
buttons[1].addEventListener('click', () => {
  result.textContent = 'The file is back in the list.';
  toast.hide();
});
toast.addEventListener('close', () => {
  result.textContent = 'The file is deleted and the toast is closed.';
});

Progress bar

show-progress draws a bar that shows the time that is left. The timer stops while the mouse pointer is over the toast.

Start the export

<zeno-button>Start the export</zeno-button>
<zeno-toast show-progress duration="8000" variant="info" title="Export started" message="We will send you an email when it is done."></zeno-toast>

document.querySelector('zeno-button').addEventListener('click', () => {
  document.querySelector('zeno-toast').show();
});

Attributes and properties

Property	Attribute	Type	Default	Description
variant	variantreflects	'default' | 'info' | 'success' | 'warning' | 'error'	'default'
position	positionreflects	'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end'	'bottom'
light	lightreflects	boolean	false
title	title	string	''
message	message	string	–
icon	icon	string	–
closable	closable	boolean	true
duration	duration	number	5000
showProgress	show-progress	boolean	false
testId	–	string	–	Test ID for automated testing From ZenoElement.

Methods

Method	Description
show(): void	Show the toast
hide(): void	Hide the toast
focus(): void	Focus the component or its first focusable element From ZenoElement.
blur(): void	Blur the component or its focused element From ZenoElement.

Events

Event	Detail	Description
show	–	The toast appeared.
hide	–	The toast finished hiding.
close	–	The close button was pressed.

Slots

Slot	Description
Default	The message.
action	A button shown with the message.

CSS parts

Part
action
base
close
content
icon
message
progress
progress-bar
title

CSS custom properties

This element documents no custom properties of its own. Style it through its parts and through the tokens it reads.

The element's own source reads no tokens.

Accessibility

Keyboard

Key	What it does
Tab	Moves focus to the action and to the close button of an open toast. The toast keeps its place in the tab order of the page.
EnterSpace	On the close button, closes the toast and sends close.

Forms

This element is not a form control. It adds nothing to a form's data.

Notes

• An open toast is a <div> with role="alert", aria-live="polite" and aria-atomic="true". A closed toast renders nothing.
• The close button is a native <button> with the aria-label “Close toast”.
• The timer stops while the mouse pointer is over the toast. duration="0" turns the timer off.
• Opening a toast does not move focus.
• With prefers-reduced-motion: reduce the slide animation and the progress transition are turned off.

Tests and known gaps

• No tests of its own. The only check is that the element registers and renders (smoke.test.ts).
• Not checked with axe-core.
• Has no Storybook story.

18 of the 28 properties, methods, events, slots and parts above have no description in the source

• the property variant
• the property position
• the property light
• the property title
• the property message
• the property icon
• the property closable
• the property duration
• the property showProgress
• the part action
• the part base
• the part close
• the part content
• the part icon
• the part message
• the part progress
• the part progress-bar
• the part title

Known gaps:

• The toast has role="alert", which is assertive, and aria-live="polite" on the same element. The two do not agree, and no attribute chooses one.
• The info, success, warning and error variants show no icon. Their default icon names are not in the icon registry, so the space for the icon stays empty.
• The variant is not given to assistive technology. It is shown by colour, and by an icon that has no text.
• The timer does not stop while keyboard focus is inside the toast, and no key closes the toast. A keyboard user may not reach the action before the toast closes.
• After the pointer leaves, the timer starts again from the full duration. The progress bar also goes back to full.
• A second show() on an open toast does not restart the timer. The first timer still runs and closes the toast early.
• closable is on by default and is a Boolean attribute, so HTML cannot turn it off. Set the closable property to false from script.
• The close button label is the fixed English text “Close toast”. No attribute changes it.
• Toasts do not stack. Two open toasts with the same position lie on top of each other.
• The progress bar runs late. Each small change of the width gets a transition as long as the whole duration, so the bar is still nearly full when the toast closes.
• The title attribute is also the native HTML title. The browser shows the same text again as a native tooltip when the pointer rests on the toast.