- Docs
- Runtime contract
Runtime contract
The observer, renderer, side effects and advanced ownership behind the shortest setup.
This page walks through what @samline/notify is, how the runtime is wired, and which side effects each public method produces. Use it as the mental model before you dive into the per-method reference under docs/api/.
When to use the runtime directly
Use the vanilla variant when you work with native HTML pages, embedded scripts, static sites, or applications where you do not need a framework wrapper. This is the primary — and only — runtime entrypoint of @samline/notify since v3.0.0. (Patch and minor releases like v3.1.0 are API-compatible.)
If you want a <script>-only setup without a bundler, see docs/browser.md.
Anatomy of the runtime
The runtime has three moving parts:
- A module-level
Observer(src/core/state.ts) — keeps an array of toasts and aSetof dismissed ids, and notifies subscribers on every change. Consumers within the same loaded module instance share this observer; separately bundled copies have their own state. - A toaster controller (
src/core/renderer.ts) — produced bycreateToaster(). It builds a single<ol data-notify-toaster>on the page, subscribes to theObserver, and reconciles a<li data-notify-toast>per active toast id. - The
toastfactory (src/api/toast.ts) — the public surface that the rest of your code talks to.toast(message, options?)and its variants just push entries into theObserver; the renderer re-renders the DOM.
The controller is returned with a small, focused method surface. update() returns the same controller; destroy() returns nothing. Read element and options as properties.
import { createToaster, toast } from '@samline/notify'
import '@samline/notify/style.css'
const toaster = createToaster({ position: 'bottom-right', richColors: true })
toaster.update({ duration: 5000 }) // bump the auto-dismiss to 5s
toaster.destroy() // unmount
toast.getHistory() and toast.getToasts() return snapshots. toast.dismiss(id) returns the supplied id; dismissing all records returns undefined.
Observable contract
Once a toaster is mounted, you can rely on the following behaviour:
- A
<ol data-notify-toaster>exists on the page with the data-attributes the stylesheet expects (data-x-position,data-y-position,data-notify-theme,data-rich-colors,data-lifted). - A
<li data-notify-toast data-id="<id>">is rendered for every active toast with its own data-attribute contract (data-type,data-styled,data-mounted,data-visible,data-front,data-expanded,data-removed, etc.). - Auto-dismiss runs on a per-toast
setTimeoutat the toast’sduration(default 4000 ms). Hovering a toast pauses the timer; moving out resumes its remaining duration. Only the loading type skips automatic dismissal; settled promise notifications use their resolved duration. - Swipe-to-dismiss works in every position via
pointerdown/pointermove/pointerup. Corner toasts swipe toward either of their edges; centered toasts swipe vertically. A swipe must pass 45 px, or be a fast flick of at least 10 px, so a tap never dismisses. document.visibilitychangepauses every active timer while the tab is hidden, and restarts them when the tab becomes visible again.- Same-id updates re-render the DOM in place. Calling
toast.loading('A', { id: 'x' })thentoast.success('B', { id: 'x' })updates the existing<li>instead of stacking a second one. The renderer fingerprints the content and re-fills only whentype,title,description,action, orcancelchanged. prefers-reduced-motionis honored in CSS. The JS still schedules timeouts but the stylesheet suppresses the animation/transition.
Lifecycle
The recommended flow:
- Mount — call
createToaster(options?)once at app entry. It mounts the singleton controller, applies the data-attributes, and applies the CSS variables the stylesheet reads. - Toast — call
toast(message, options?)(or one of its variants) anywhere in your app. The toast is added to theObserver; the controller renders a<li>synchronously through the subscribed renderer. - Update — call
toaster.update(options?)to re-render the container with new options. Useful for live theme or position changes. - Resolve promises —
toast.promise(promise, { loading, success, error })ties a loading → success/error transition to a realPromise, reusing the same id. - Dismiss — toasts auto-dismiss after their
duration. Calltoast.dismiss(id)(ortoast.dismiss()to drop them all) to dismiss early. - Destroy — call
destroyToaster()(ortoaster.destroy()) to unmount the container, clear every timer, and remove the renderer. destroyToaster() additionally publishes global dismissals; controller.destroy() does not.
Side effects per method
Use this as a quick lookup when you need to know what a method will touch.
| Method | DOM mutation | Timers scheduled | Subscribers notified | Toaster state touched |
|---|---|---|---|---|
toast |
yes (adds a <li>) |
yes (auto-dismiss) | yes | none |
toast.success / error / info / warning / loading / message |
yes (adds a <li>) |
yes (no timer for loading) |
yes | none |
toast.promise |
yes (adds a loading <li>, then updates in place) |
no on the loading variant | on loading and result, when supplied | none |
toast.custom |
yes (mounts the provided HTMLElement or runs the callback) |
yes (auto-dismiss) | yes | none |
toast.dismiss |
yes (marks data-removed; removes <li> after exit; 200 ms fallback) |
yes (clears pending timer) | yes | none |
toast.getHistory / toast.getToasts |
no | no | no | none |
createToaster |
yes (mounts <ol>; appends to document.body) |
buffered records may start timers | no (subscribes once) | sets the singleton |
createToaster (called twice) |
updates the singleton in place via update() |
updated when duration changes | no | updates the singleton |
toaster.update(options?) |
re-applies data-attributes and CSS variables | updated when duration changes | no | updates internal options |
toaster.destroy() |
removes the <ol> from the DOM |
clears all timers | unsubscribes the renderer | clears the singleton |
destroyToaster |
same as toaster.destroy(), plus drops all toasts |
clears all timers | yes (one per dropped toast) | clears the singleton |
getToaster |
no | no | no | none (read-only) |
configureToaster |
same as createToaster(options?) |
updated when duration changes | no | updates the singleton |
resetToasts |
yes (drops all <li>s) |
clears all timers | yes | none |
Recommended usage patterns
- Use
toast.promisefor any async flow that already returns aPromise— it ties loading/success/error to one id and updates the DOM in place. - Use the
actionandcanceloptions for undo/redo flows; both default to closing the toast on click. - Use
toast.custom(element | (container) => void)for rich content. Pass a pre-builtHTMLElementyou own, or a callback that fills a container. No JSX, no React nodes, noinnerHTMLof user input. - For themes, override the
--normal-bg/--normal-text/--normal-border/--success-bg/ etc. CSS variables on[data-notify-toaster][data-notify-theme="<theme>"]— see CSS styling. - Call
toaster.update({ position, theme, dir })to react to live changes (e.g. when the user toggles dark mode). - Call
toaster.destroy()whenever a toaster is mounted and unmounted dynamically (SPA route changes, conditional rendering, modals).destroyToaster()is a no-op if none is mounted.
Browser registry helpers
The browser IIFE bundle ships a single global (window.Notify) that wraps toast + createToaster + getToaster + destroyToaster + configureToaster. The registry is available from the vanilla entrypoint as a module-level singleton called browser:
import { browser, Notify } from '@samline/notify'
import '@samline/notify/style.css'
browser === Notify // true
window.MyNotify = { ...browser }
window.MyNotify.createToaster({ position: 'bottom-right' })
window.MyNotify.toast.success('Saved')
window.MyNotify.destroyToaster()
browser is an object you can spread into your own globals or use directly. Because it shares the same module-level Observer and the same toaster singleton as the named exports, every spread behaves the same — window.MyNotify.createToaster({}) and createToaster({}) end up calling the same factory and updating the same DOM container.
Notify is the namespace-oriented name for that same object. The root and browser module share the registry within the same module graph. The standalone script contains its own bundled instance. Do not mix independently loaded package instances and assume shared state.
For multiple containers, use mountToaster and own each controller. Their default stream is shared; separate containers are not separate state, history or counters. Inject isolated state only in an advanced integration.
import { mountToaster } from '@samline/notify'
const left = mountToaster(document.body, { position: 'bottom-left' })
const right = mountToaster(document.body, { position: 'bottom-right' })
// left and right have their own <ol> + timers + cleanups.
left.destroy()
right.destroy()
mountToaster accepts the DOM root (the <ol> will be appended to it), the ToasterOptions, and an optional state parameter for tests that need a fresh Observer. Use the named exports (createToaster, getToaster, destroyToaster) for the common case of one toaster per page.
Submission examples
toast.promise with fetch
import { toast } from '@samline/notify'
async function saveProfile(patch: object): Promise<{ name: string }> {
const response = await fetch('/api/profile', {
method: 'PATCH',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(patch),
})
if (!response.ok) {
throw new Error(`Profile save failed: ${response.status}`)
}
return response.json()
}
toast.promise(saveProfile({ name: 'Nora' }), {
loading: 'Saving profile…',
success: profile => `Saved as ${profile.name}`,
error: 'Could not save your profile',
})
The loading toast appears immediately, the same <li> updates in place to success or error once the promise settles, and the id you get back is the same for both phases. Omit loading to show only a configured settled notification. Use the returned unwrap() to read the original promise outcome. Omit all display data to obtain a passthrough without rendering.
Next steps
- Need a full options reference? See docs/options.md.
- Looking up the exact signature of a method? See docs/api/index.md.
- Working with the type system? See docs/typescript.md.
- Want end-to-end patterns? See docs/recipes.md.
- Want the stylesheet contract? See docs/css-styling.md.
- Working with the IIFE bundle? See docs/browser.md.