@marccawood/lit-toast

A non-modal toast queue as one Lit web component. Stacks at top-center, auto-dismisses, links URLs in the message.

Depends only on lit.

Live example → — cd example && npm install && npm run dev

For modal dialogs see the sibling package @marccawood/lit-dialogs.

Install

npm install @marccawood/lit-toast lit

Use

import { ToastHost, defineToastHost } from '@marccawood/lit-toast';

defineToastHost();

Render one element in your app shell:

<toast-host></toast-host>

Then show a toast from anywhere through the singleton:

ToastHost.instance?.show('Import finished', { kind: 'success' });
ToastHost.instance?.show('Could not reach the server', { kind: 'error', title: 'Sync' });
ToastHost.instance?.show('Saved', { durationMs: 1500 });

show is fire-and-forget — it returns nothing, because nobody waits for a toast. Contrast a dialog, which returns a promise because it waits for a person.

| Option | Default | | ------------ | --------------------------------------------------------- | | kind | 'info' — one of info, success, warning, error | | title | none — renders as a bold first line | | durationMs | 4000 for info / success, 7000 for warning / error |

The × dismisses one early. Toasts stack; they do not replace each other. A URL in the message becomes a link — the message is split by linkify, never parsed as HTML.

defineToastHost(tag) takes an optional tag name and skips an already-registered tag, so importing the module twice is safe.

Theme

Set these on any ancestor. Every one falls back to the value shown.

| Token | Fallback | | ----------------- | ------------------------------- | | --toast-top | 56px — clears your header bar | | --toast-surface | Canvas | | --toast-radius | 0.35rem | | --toast-success | #16a34a | | --toast-error | #dc2626 | | --toast-warning | #d97706 | | --toast-info | #2563eb |

Icons

The four kind icons are Material Icons glyphs. Load the font once globally in your app:

import 'material-icons/iconfont/material-icons.css';

Without it the toast shows the glyph names as text.

materialIconStyles is exported for your own shadow-DOM components — class rules in the document stylesheet do not reach inside a shadow root, so each component needs a copy.

API

| Export | What it is | | -------------------- | ----------------------------------------------------------------- | | ToastHost | The element class. ToastHost.instance is the mounted singleton. | | defineToastHost | Guarded customElements.define, default tag toast-host. | | ToastKind | 'info' \| 'success' \| 'warning' \| 'error' | | linkify | Splits a string into text and URL links. Pure, tested. | | materialIconStyles | Material Icons class rules for your own shadow roots. |

Develop

npm install
npm run typecheck
npm test
npm run build

Publishing runs from a version tag. Push v0.1.0 and the publish workflow checks the tag against package.json, runs the tests, and publishes to npm.

Origin

Extracted from easyDBAccess. It started out next to the dialogs there, which was wrong — a toast is a notification, not a dialog, and the two share no code.

License

MIT © Marc Cawood