Overview & Philosophy
ln-toast is applied to a <ul data-ln-toast> live region container. It listens globally on window for ln-toast:enqueue CustomEvents: upon receiving an event, it clones the toast template (<template data-ln-template="ln-toast-item">), appends the notification item to the container, and initiates an automatic dismiss countdown. On timeout or dismiss button click, it animates out with .closing and removes the element from the DOM upon animation completion.
It is a service-style, zero-markup component that handles a dynamic queue of alert cards without requiring components to import or know about toast internals.
The Toast Doctrine
Toasts are completely decoupled from UI producers. Components never import or call toast APIs directly. To trigger a notification, any script or component anywhere in the page simply dispatches an ln-toast:enqueue event on the window object. The central toast coordinator catches the event, adds it to the rendering queue, and handles the DOM. The window event is the sole contract.
Dynamic Features & Sizing
- Automatic Dismissal: Every toast card automatically triggers its close animation after 6 seconds. If a user hovers over a toast, the timer is paused, resuming once the mouse leaves.
- Validation Lists: If the
messagedetail is an array of strings, the toast automatically renders it as an unordered list, perfect for displaying multiple form validation errors in a single compact card. - Categorized Types: Supports
success(green accent),error(red accent),warn(yellow accent), andinfo(blue accent) with matching icon sprites dynamically loaded.
For the complete developer reference, see the ln-toast README and the architecture reference.
Examples
To display a notification programmatically, dispatch a custom event to the window object: window.dispatchEvent(new CustomEvent('ln-toast:enqueue', { detail: { type: 'success', title: 'Title', message: 'Message' } })).
Error with a list of errors
Toasts support an array of strings in message to render a bulleted list of errors: message: ['Error 1', 'Error 2'].
SSR-authored flash messages (no JS render)
Server-rendered flash messages are authored as complete markup — icon, title, body, and close button are all real HTML written by the backend template. ln-toast only binds behavior on load: it starts the auto-dismiss timer and wires the close button. This markup is fully readable even before JS executes.
An optional per-item data-ln-toast-timeout overrides the container default — use 0 for a persistent toast such as a blocking error.
-
Saved Changes have been saved successfully.
-
Session Expired This toast overrides the container default and auto-dismisses after 8 seconds.