Holo Toast & Holo Toast Region

<holo-toast-region> is a fixed-position, aria-live="polite" container typically placed once per page. It manages a stack of <holo-toast> children and exposes an addToast() method for creating them programmatically. Individual <holo-toast> elements support a manual close button and an auto-dismiss timer that pauses on hover/focus.

When to use

Use it for:

• Brief, non-blocking feedback after an action: “Saved”, “Copied”, “Message sent”.
• Notices that can disappear without the user needing to act.

Don’t use it for:

• Errors or messages the user must read and act on. Use Alert or Dialog.
• Messages with actions or links the user may not reach in time. Use Alert.
• Persistent status inside a layout. Use Alert or Badge.

Live Previews

Toast variants

Changes saved.Upload complete.Storage almost full.Failed to save changes.

<holo-toast variant="info">Changes saved.</holo-toast> <holo-toast variant="success">Upload complete.</holo-toast>

Toast region with addToast()

Add toast

<holo-toast-region position="bottom-end"></holo-toast-region>
<script>
  const region = document.querySelector('holo-toast-region');
  region.addToast({ message: 'Changes saved.', variant: 'success', duration: 4000 });
</script>

Accessibility

<holo-toast-region> is a live region (aria-live="polite", aria-atomic="false") that holds toasts and positions them with position. Each <holo-toast> has role="status" and aria-atomic="true", so its message is announced politely when added to the region. The icon is aria-hidden. Every toast has a native dismiss <button> named “Dismiss notification”. The region itself is not a landmark and is not focusable.

Key	Action
Tab	Moves focus to a toast’s dismiss button (in DOM order)
Enter, Space	Dismisses the toast, which fires holoDismiss

• Set duration (ms) to auto-dismiss. Without it the toast stays until dismissed.
• The auto-dismiss timer pauses while the pointer is over the toast or focus is inside it, and resumes afterwards.
• Toasts added with addToast() are removed on holoDismiss. Toasts you create yourself must be removed by your own holoDismiss handler.
• The dismiss button shows a visible focus ring with :focus-visible.
• The entry animation only runs when prefers-reduced-motion: no-preference.

You provide:

• Message text that is complete on its own and brief. The text is all that is announced.
• A long enough duration for the message to be read, or none. Do not use toasts for anything critical.
• A holo-toast-region in the page before you add toasts, so the live region already exists when content arrives.

---

API Reference

holo-toast

Importing

import '@philbob-sideprojects/hololink-ui/holo-toast';

Properties

Property	Attribute	Type	Default	Description
duration	duration	number	—	Milliseconds before the toast auto-dismisses. Omit (or set 0) to require manual dismissal. The timer pauses while the toast has hover or focus.
variant	variant	"danger" | "info" | "success" | "warning"	'info'	The severity/style of the toast.

Events

Event	Detail	Description
holoDismiss	void	Emitted when the toast is dismissed (manually or via the auto-dismiss timer). The toast does not remove itself; holo-toast-region removes toasts it created with addToast().

Slots

Slot	Description
(default)	The notification message.

CSS custom properties

Property	Description
--holo-toast-accent-color	Color of the leading accent border and icon. Defaults to the status color of the current variant.
--holo-toast-bg	Background color of the toast.
--holo-toast-border-color	Border color of the toast.
--holo-toast-padding	Inner padding of the toast.
--holo-toast-radius	Corner radius of the toast.
--holo-toast-shadow	Box shadow of the toast.
--holo-toast-text-color	Text color of the toast.

holo-toast-region

Importing

import '@philbob-sideprojects/hololink-ui/holo-toast-region';

Properties

Property	Attribute	Type	Default	Description
position	position	"bottom-end" | "bottom-start" | "top-end" | "top-start"	'bottom-end'	Which corner/edge of the viewport the toast stack is anchored to.

Methods

Signature	Description
addToast(options: HoloToastOptions) => Promise<HTMLElement>	Creates a holo-toast, appends it to the region, and removes it from the DOM when dismissed. options is `{ message: string; variant?: 'info' | 'success' | 'warning' | 'danger'; duration?: number }`. Resolves with the created toast element.

Slots

Slot	Description
(default)	Toasts to render in the region. Toasts created with addToast() are appended here.