Accessible, dependency-free toast notifications for JavaScript, TypeScript and plain HTML. Mount one owned toaster at the client root and emit semantic, promise-driven or custom notifications from anywhere.
Demo · Examples · Documentation · Changelog
- Installation
- Quick start
- HTML / CDN
- Capabilities
- API at a glance
- Documentation
- Changelog
- AI agent skill
- License
npm install @samline/notifypnpm add @samline/notifybun add @samline/notifyRequires Node 20+ when bundling. Runtime target is ES2020.
Import the stylesheet once in your application entrypoint:
import '@samline/notify/style.css'Run once at your application's client root, after document.body exists. Keep the returned controller: it owns preference updates and cleanup.
import { createToaster, destroyToaster, toast } from '@samline/notify'
import '@samline/notify/style.css'
const toaster = createToaster({
position: 'bottom-right',
richColors: true,
closeButton: true,
theme: 'system',
})
toast.success('Changes saved')
toast.error('Could not save', { description: 'Check your connection and try again.' })
toaster.update({ position: 'top-center' })
// When the owning application or page leaves:
destroyToaster()What this does:
- Mounts a singleton toaster (one per page) with the position, color treatment and theme you requested. Calling
createToaster()again updates the same instance. - Renders each notification as native DOM inside a labelled live region; actions and close buttons are real
buttonelements. - Lets the stylesheet own layout, stacking and appearance through data attributes, while the renderer supplies measured geometry through CSS custom properties. No shadow DOM.
- Pauses a toast's timer while it is hovered or focused, and every timer while the document is hidden, then resumes from the remaining time.
- Keeps
toaster.update()partial: omitted options remain unchanged. - Disposes the renderer and dismisses active notifications when
destroyToaster()runs.
Root and module imports are safe without a DOM; mounting is client-only. See the toast lifecycle guide for remounting and lower-level controller ownership.
Choose Package / ESM when installing with npm, pnpm or bun and importing Notify in your application. Choose HTML / CDN when loading the standalone script in plain HTML, WordPress or Shopify without a bundler. Both use the same toast API. A CDN only delivers the files; you can self-host the same script and stylesheet.
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@samline/notify@5.0.1/dist/style.css" />
<script src="https://cdn.jsdelivr.net/npm/@samline/notify@5.0.1/dist/browser/notify.global.js"></script>Pin the version in production. Replace
4.0.0with the version you ship.
The standalone script (an IIFE) exposes window.Notify and auto-mounts a default toaster once, so the first call has somewhere to render. The optional @samline/notify/browser registry module is an ESM/CJS import; it does not install that object or auto-mount.
<button id="save" type="button">Save</button>
<script>
const notify = window.Notify
notify.createToaster({ position: 'top-center', richColors: true })
document.querySelector('#save').addEventListener('click', () => {
notify.toast.success('Saved')
})
</script>createToaster(options) updates the auto-mounted toaster; after destroyToaster(), remount explicitly. See Browser integration for the complete registry, base paths and Content Security Policy notes.
- Action confirmations ("Saved", "Copied to clipboard", "Email sent") with auto-dismiss.
- Async feedback with
toast.promise()for fetches, uploads and any otherPromiseflow. - Progress that reuses one toast id from loading to its terminal state.
- Undo and retry flows through native
actionandcancelbuttons. - Rich per-toast content through
toast.custom(element)or a factory, without JSX. - Light, dark and system themes, rich colors, RTL and keyboard shortcuts.
- Browser-global integrations for WordPress, Shopify and plain HTML.
Working examples cover semantic variants, promises, cancellation, actions, editable custom content and stack interaction. Framework integrations covers React, Vue, Svelte and SSR using this same API.
Strings are rendered as text. action closes the toast unless closeOnClick is false or onClick calls event.preventDefault(); cancel renders before it. Use a label that names the result, such as Undo deletion.
toast('Message archived', {
action: { label: 'Undo archive', onClick: () => console.log('restore') },
duration: 6000,
})Custom factories can run again after controller updates: keep draft state outside the factory and release listeners on replacement or dismissal. Never put an aria-label on a toast item; it would replace its description, actions and content for assistive technology. See actions and custom content and accessibility.
| API | Purpose |
|---|---|
toast() |
Toast factory |
success() · error() · info() · warning() · loading() · message() |
Toast variants |
toast.custom() · toast.promise() |
Content and async |
toast.dismiss() · toast.getToasts() · toast.getHistory() |
Dismissal and state |
createToaster() · getToaster() · configureToaster() · destroyToaster() · resetToasts() |
Toaster lifecycle |
ToasterOptions and ToastOptions |
Configuration |
mountToaster(), ToastState and runtime contract |
Advanced rendering |
| TypeScript reference | Types |
The controller exposes element and an options snapshot. update(options?) is chainable and partial; destroy() removes that renderer, while destroyToaster() also dismisses active notifications. Direct mountToaster() calls share the default ToastState unless you supply another one, so separate containers are not independent channels.
See the complete API reference.
| Entrypoint | When to use |
|---|---|
@samline/notify |
Main API, browser registry singleton, types and constants. |
@samline/notify/browser |
ESM/CJS browser registry without a global side effect. |
dist/browser/notify.global.js (CDN file) |
Pre-bundled IIFE that installs window.Notify and auto-mounts. |
@samline/notify/style.css |
Required layout, stacking, theme and motion styles. |
The main entrypoint also exports browser and its Notify alias: the same { toast, Toaster, createToaster, configureToaster, getToaster, destroyToaster } registry as the standalone script, without installing window.Notify. See Entrypoints.
Continue from the Quick start with your application's promise. This example expects /api/profile to return JSON containing a name; replace that endpoint with your own.
async function fetchProfile(): Promise<{ name: string }> {
const response = await fetch('/api/profile')
if (!response.ok) throw new Error('Could not load profile')
return response.json()
}
const result = toast.promise(fetchProfile(), {
loading: 'Loading profile…',
success: profile => `Hi ${profile.name}`,
error: 'Could not load profile',
})
const profile = await result.unwrap()toast.promise() updates one id when a loading message is supplied. unwrap() preserves the original outcome; a fulfilled non-ok HTTP response can show the error state while still fulfilling. Cancellation belongs to the application. See the promise contract and examples.
Read the documentation for the full guides and API contracts, and explore working examples with complete and separate source files for both loading modes.
| Guide | What it covers |
|---|---|
| Getting started | Installation, stylesheet, first notification and ownership. |
| Toast lifecycle | Singleton mounting, updates, remounting and teardown. |
| Configuration | Every toaster and toast option, default and inheritance rule. |
| Promises | Complete toast.promise() behavior, HTTP values and unwrap(). |
| Actions and custom content | Action buttons, custom DOM factories and listener cleanup. |
| Browser integration | window.Notify, the module registry, hosting and CSP. |
| Entrypoints | ESM, CommonJS, registries, the standalone IIFE and stylesheet loading. |
| Styling | Data-attribute contract, classes and CSS custom properties. |
| Accessibility | Semantics, keyboard controls, timing and accessible content. |
| Framework integrations | Lifecycle-safe React, Vue, Svelte and SSR patterns. |
| TypeScript | Exported TypeScript types and their roles. |
| Troubleshooting | Mounting, CSS, duplicate renderers, CDN, CSP and teardown fixes. |
| API reference | Factory variants, singleton lifecycle, state and low-level rendering. |
Read CHANGELOG.md or the published changelog for release history and explicitly marked breaking and behavior changes. Review the notes before upgrading.
V4 exposes the registry directly as window.Notify (3.2.0 and earlier wrapped it in a namespace), dispatches onDismiss once from shared state regardless of how many toasters are mounted, and changes the custom-content DOM. See CHANGELOG.md before upgrading 3.x code.
The public Notify skill teaches an agent how to mount one owned toaster, load CSS, match feedback to the task, manage custom content and clean up without inventing APIs. It is self-contained and describes v4.0.0; agents must verify their installed version.
The maintained repository source and website download are the same file.
Download SKILL.md into a notify/ folder in your agent's supported skill directory. For agents that discover project skills from .agents/skills/:
mkdir -p .agents/skills/notify
curl --fail --location https://samline.github.io/notify/skills/notify/SKILL.md \
--output .agents/skills/notify/SKILL.mdWhen working from this repository, copy skills/notify/SKILL.md instead. Keep the filename SKILL.md; discovery paths and invocation syntax depend on the agent.
MIT — LICENSE.md.