Guide

Getting started

Install @samline/notify, import the stylesheet, mount one toaster, and send your first toast.

Start with one mounted toaster and one notification. Choose package imports for a bundled app, or the complete HTML / CDN file for a page without a build step.

This guide documents 4.0.0. The live preview runs the same source.

Install

Terminal
npm install @samline/notify
Terminal
pnpm add @samline/notify
Terminal
yarn add @samline/notify
Terminal
bun add @samline/notify
Terminal
<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" defer></script>

The package ships ESM, CommonJS, and browser builds. The root entrypoint is side-effect free: importing it installs no global and touches no DOM.

Import the stylesheet

The renderer writes attributes and text; the packaged stylesheet turns those into layout, transitions, and palette. Import it once, in the client entrypoint of your application.

import '@samline/notify/style.css'

Without the stylesheet the runtime still produces a semantic live list, but it has no fixed layout, no stack transitions, and no built-in button presentation.

Mount one toaster

createToaster() mounts the singleton renderer on document.body. Call it once, from client-side code, after the document body exists.

import { createToaster, toast } from '@samline/notify'
import '@samline/notify/style.css'

createToaster({ position: 'bottom-right' })

toast.success('Notify is ready')

Calling createToaster() again does not append a second container. It applies the new options to the existing toaster and returns the same controller.

Mounting needs a DOM

createToaster() throws when there is no document, and throws again when document.body is not ready yet. Move the call into your framework’s client lifecycle hook, or wait for DOMContentLoaded. The standalone build already handles this for its own first mount.

Working starter files

Everything above, in one folder. The complete example loads the published browser build, mounts one toaster, and sends real toasts — no install and no build step.

index.html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>A save worth confirming</title>
    <link
      rel="stylesheet"
      href="https://cdn.jsdelivr.net/npm/@samline/notify@5.0.1/dist/style.css"
    />
    <link rel="stylesheet" href="./style.css" />
  </head>
  <body>
    <main
      style="max-width: 48rem; margin: 2rem auto; padding: 1rem; font-family: system-ui, sans-serif"
    >
      <section
        class="notify-demo"
        data-notify-demo
        data-preset="save"
        aria-label="Profile settings"
      >
        <p class="notify-demo-eyebrow">Profile settings</p>
        <strong class="notify-demo-heading">A little more like you.</strong>
        <p class="notify-demo-description">
          Update your public display name. Nothing leaves this page.
        </p>
        <label class="notify-demo-field"
          >Display name<input
            type="text"
            value="Nora Quinn"
            required
            maxlength="60"
            autocomplete="name"
        /></label>

        <p class="notify-demo-result" data-demo-result role="status">Your profile is up to date.</p>
        <div class="notify-demo-actions">
          <button type="button" data-demo-action>Save changes</button>

          <button type="button" data-demo-reset>Reset this preview</button>
        </div>
      </section>
    </main>
    <script src="https://cdn.jsdelivr.net/npm/@samline/notify@5.0.1/dist/browser/notify.global.js"></script>
    <script src="./main.js"></script>
  </body>
</html>
style.css
/* Demo form only. Toast appearance and motion come from @samline/notify/style.css. */
.notify-demo {
  display: grid;
  gap: 1rem;
  min-width: 0;
  color: #26232b;
}
.notify-demo-eyebrow {
  font: 0.625rem/1.6 monospace;
  letter-spacing: 0.12em;
  text-transform: uppercase;
  color: #655d68;
}
.notify-demo-heading {
  font-size: clamp(1.4rem, 3vw, 1.9rem);
  line-height: 1.25;
  font-weight: 500;
  letter-spacing: -0.035em;
}
.notify-demo-description {
  max-width: 45rem;
  color: #5f5763;
  line-height: 1.7;
}
.notify-demo p {
  margin: 0;
}
.notify-demo-field {
  display: grid;
  gap: 0.5rem;
  min-width: 0;
  max-width: 28rem;
  color: #5f5763;
  font-size: 0.8125rem;
}
.notify-demo-field input {
  display: block;
  box-sizing: border-box;
  min-width: 0;
  width: 100%;
  min-height: 3.125rem;
  padding: 0.75rem 1rem;
  font:
    400 1rem/1.5 system-ui,
    sans-serif;
  color: #26232b;
  background: #f4f2f7;
  border: 0.0625rem solid #b7adb9;
  border-radius: 0.5rem;
}
.notify-demo-field input {
  cursor: text;
}
.notify-demo-field input:disabled {
  opacity: 0.5;
  cursor: not-allowed;
}
@media (hover: hover) {
  .notify-demo-field input:enabled:hover {
    border-color: #8d7a98;
  }
}
.notify-demo-result {
  min-height: 1.5rem;
  font-size: 0.8125rem;
  color: #5f5763;
}
.notify-demo-actions {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 0.625rem;
  padding-top: 0.5rem;
}
.notify-demo-actions button {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  box-sizing: border-box;
  min-height: 3.125rem;
  padding: 0.5rem 1.4rem;
  font:
    500 0.875rem/1.5 system-ui,
    sans-serif;
  letter-spacing: -0.01em;
  cursor: pointer;
  border: 0.0625rem solid #b7adb9;
  border-radius: 0.875rem;
  color: #26232b;
  background: #f4f2f7;
}
.notify-demo-actions [data-demo-action] {
  background: #b45309;
  border-color: transparent;
  color: #fff;
}
.notify-demo-actions [data-demo-reset] {
  min-height: 2.5rem;
  padding-inline: 1rem;
  border-radius: 624.9375rem;
  color: #5f5763;
  border-color: #b7adb9;
  background: transparent;
}
.notify-demo-actions button:disabled {
  opacity: 0.5;
  cursor: not-allowed;
}
@media (hover: hover) {
  .notify-demo-actions button:enabled:hover {
    background: #e8e5ed;
    border-color: #8d7a98;
  }
  .notify-demo-actions [data-demo-action]:enabled:hover {
    background: #92400e;
    border-color: transparent;
  }
  .notify-demo-actions [data-demo-reset]:enabled:hover {
    color: #b45309;
    background: #fef3c7;
  }
}
.notify-demo :focus-visible {
  outline: 0.125rem solid #b45309;
  outline-offset: 0.1875rem;
}
.notify-demo [hidden] {
  display: none;
}
.notify-demo-actions button {
  overflow-wrap: anywhere;
  max-width: 100%;
}
main.js
const notify = window.Notify

const copy = { saving: 'Saving your profile…', saved: 'Profile saved' }

const saveDemo = (element, notify, copy, signal) => {
  const input = element.querySelector('input')
  const action = element.querySelector('[data-demo-action]')
  const result = element.querySelector('[data-demo-result]')
  const initial = result.textContent
  let pending = new AbortController()

  action.addEventListener(
    'click',
    () => {
      const name = input.value.trim()
      if (!name) return input.reportValidity()

      notify.createToaster({ richColors: true, closeButton: true })
      action.disabled = true
      const saving = wait(1200, pending.signal).then(done => {
        if (!done) throw new DOMException('Reset', 'AbortError')
        return name
      })
      notify.toast.promise(saving, {
        loading: copy.saving,
        success: saved => {
          result.textContent = `${copy.saved}: ${saved}`
          action.disabled = false
          return { message: copy.saved, description: saved }
        },
      })
    },
    { signal }
  )

  element.querySelector('[data-demo-reset]').addEventListener(
    'click',
    () => {
      pending.abort()
      pending = new AbortController()
      notify.toast.dismiss()
      action.disabled = false
      result.textContent = initial
    },
    { signal }
  )
}

// Resolves true after `ms`, or false as soon as `signal` aborts.
const wait = (ms, signal) =>
  new Promise(resolve => {
    const timer = setTimeout(resolve, ms, true)
    signal.addEventListener(
      'abort',
      () => {
        clearTimeout(timer)
        resolve(false)
      },
      { once: true }
    )
  })

saveDemo(document.querySelector('[data-notify-demo]'), notify, copy)

// A page that is leaving no longer needs its toaster.
window.addEventListener('pagehide', event => {
  if (!event.persisted) notify.destroyToaster()
})
index.html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>A save worth confirming</title>
    <link
      rel="stylesheet"
      href="https://cdn.jsdelivr.net/npm/@samline/notify@5.0.1/dist/style.css"
    />
    <style>
      /* Demo form only. Toast appearance and motion come from @samline/notify/style.css. */
      .notify-demo {
        display: grid;
        gap: 1rem;
        min-width: 0;
        color: #26232b;
      }
      .notify-demo-eyebrow {
        font: 0.625rem/1.6 monospace;
        letter-spacing: 0.12em;
        text-transform: uppercase;
        color: #655d68;
      }
      .notify-demo-heading {
        font-size: clamp(1.4rem, 3vw, 1.9rem);
        line-height: 1.25;
        font-weight: 500;
        letter-spacing: -0.035em;
      }
      .notify-demo-description {
        max-width: 45rem;
        color: #5f5763;
        line-height: 1.7;
      }
      .notify-demo p {
        margin: 0;
      }
      .notify-demo-field {
        display: grid;
        gap: 0.5rem;
        min-width: 0;
        max-width: 28rem;
        color: #5f5763;
        font-size: 0.8125rem;
      }
      .notify-demo-field input {
        display: block;
        box-sizing: border-box;
        min-width: 0;
        width: 100%;
        min-height: 3.125rem;
        padding: 0.75rem 1rem;
        font:
          400 1rem/1.5 system-ui,
          sans-serif;
        color: #26232b;
        background: #f4f2f7;
        border: 0.0625rem solid #b7adb9;
        border-radius: 0.5rem;
      }
      .notify-demo-field input {
        cursor: text;
      }
      .notify-demo-field input:disabled {
        opacity: 0.5;
        cursor: not-allowed;
      }
      @media (hover: hover) {
        .notify-demo-field input:enabled:hover {
          border-color: #8d7a98;
        }
      }
      .notify-demo-result {
        min-height: 1.5rem;
        font-size: 0.8125rem;
        color: #5f5763;
      }
      .notify-demo-actions {
        display: flex;
        flex-wrap: wrap;
        align-items: center;
        gap: 0.625rem;
        padding-top: 0.5rem;
      }
      .notify-demo-actions button {
        display: inline-flex;
        align-items: center;
        justify-content: center;
        box-sizing: border-box;
        min-height: 3.125rem;
        padding: 0.5rem 1.4rem;
        font:
          500 0.875rem/1.5 system-ui,
          sans-serif;
        letter-spacing: -0.01em;
        cursor: pointer;
        border: 0.0625rem solid #b7adb9;
        border-radius: 0.875rem;
        color: #26232b;
        background: #f4f2f7;
      }
      .notify-demo-actions [data-demo-action] {
        background: #b45309;
        border-color: transparent;
        color: #fff;
      }
      .notify-demo-actions [data-demo-reset] {
        min-height: 2.5rem;
        padding-inline: 1rem;
        border-radius: 624.9375rem;
        color: #5f5763;
        border-color: #b7adb9;
        background: transparent;
      }
      .notify-demo-actions button:disabled {
        opacity: 0.5;
        cursor: not-allowed;
      }
      @media (hover: hover) {
        .notify-demo-actions button:enabled:hover {
          background: #e8e5ed;
          border-color: #8d7a98;
        }
        .notify-demo-actions [data-demo-action]:enabled:hover {
          background: #92400e;
          border-color: transparent;
        }
        .notify-demo-actions [data-demo-reset]:enabled:hover {
          color: #b45309;
          background: #fef3c7;
        }
      }
      .notify-demo :focus-visible {
        outline: 0.125rem solid #b45309;
        outline-offset: 0.1875rem;
      }
      .notify-demo [hidden] {
        display: none;
      }
      .notify-demo-actions button {
        overflow-wrap: anywhere;
        max-width: 100%;
      }
    </style>
  </head>
  <body>
    <main
      style="max-width: 48rem; margin: 2rem auto; padding: 1rem; font-family: system-ui, sans-serif"
    >
      <section
        class="notify-demo"
        data-notify-demo
        data-preset="save"
        aria-label="Profile settings"
      >
        <p class="notify-demo-eyebrow">Profile settings</p>
        <strong class="notify-demo-heading">A little more like you.</strong>
        <p class="notify-demo-description">
          Update your public display name. Nothing leaves this page.
        </p>
        <label class="notify-demo-field"
          >Display name<input
            type="text"
            value="Nora Quinn"
            required
            maxlength="60"
            autocomplete="name"
        /></label>

        <p class="notify-demo-result" data-demo-result role="status">Your profile is up to date.</p>
        <div class="notify-demo-actions">
          <button type="button" data-demo-action>Save changes</button>

          <button type="button" data-demo-reset>Reset this preview</button>
        </div>
      </section>
    </main>
    <script src="https://cdn.jsdelivr.net/npm/@samline/notify@5.0.1/dist/browser/notify.global.js"></script>
    <script>
      const notify = window.Notify

      const copy = { saving: 'Saving your profile…', saved: 'Profile saved' }

      const saveDemo = (element, notify, copy, signal) => {
        const input = element.querySelector('input')
        const action = element.querySelector('[data-demo-action]')
        const result = element.querySelector('[data-demo-result]')
        const initial = result.textContent
        let pending = new AbortController()

        action.addEventListener(
          'click',
          () => {
            const name = input.value.trim()
            if (!name) return input.reportValidity()

            notify.createToaster({ richColors: true, closeButton: true })
            action.disabled = true
            const saving = wait(1200, pending.signal).then(done => {
              if (!done) throw new DOMException('Reset', 'AbortError')
              return name
            })
            notify.toast.promise(saving, {
              loading: copy.saving,
              success: saved => {
                result.textContent = `${copy.saved}: ${saved}`
                action.disabled = false
                return { message: copy.saved, description: saved }
              },
            })
          },
          { signal }
        )

        element.querySelector('[data-demo-reset]').addEventListener(
          'click',
          () => {
            pending.abort()
            pending = new AbortController()
            notify.toast.dismiss()
            action.disabled = false
            result.textContent = initial
          },
          { signal }
        )
      }

      // Resolves true after `ms`, or false as soon as `signal` aborts.
      const wait = (ms, signal) =>
        new Promise(resolve => {
          const timer = setTimeout(resolve, ms, true)
          signal.addEventListener(
            'abort',
            () => {
              clearTimeout(timer)
              resolve(false)
            },
            { once: true }
          )
        })

      saveDemo(document.querySelector('[data-notify-demo]'), notify, copy)

      // A page that is leaving no longer needs its toaster.
      window.addEventListener('pagehide', event => {
        if (!event.persisted) notify.destroyToaster()
      })
    </script>
  </body>
</html>
index.html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>A save worth confirming</title>
  </head>
  <body>
    <main
      style="max-width: 48rem; margin: 2rem auto; padding: 1rem; font-family: system-ui, sans-serif"
    >
      <section
        class="notify-demo"
        data-notify-demo
        data-preset="save"
        aria-label="Profile settings"
      >
        <p class="notify-demo-eyebrow">Profile settings</p>
        <strong class="notify-demo-heading">A little more like you.</strong>
        <p class="notify-demo-description">
          Update your public display name. Nothing leaves this page.
        </p>
        <label class="notify-demo-field"
          >Display name<input
            type="text"
            value="Nora Quinn"
            required
            maxlength="60"
            autocomplete="name"
        /></label>

        <p class="notify-demo-result" data-demo-result role="status">Your profile is up to date.</p>
        <div class="notify-demo-actions">
          <button type="button" data-demo-action>Save changes</button>

          <button type="button" data-demo-reset>Reset this preview</button>
        </div>
      </section>
    </main>

    <script type="module" src="./main.js"></script>
  </body>
</html>
style.css
/* Demo form only. Toast appearance and motion come from @samline/notify/style.css. */
.notify-demo {
  display: grid;
  gap: 1rem;
  min-width: 0;
  color: #26232b;
}
.notify-demo-eyebrow {
  font: 0.625rem/1.6 monospace;
  letter-spacing: 0.12em;
  text-transform: uppercase;
  color: #655d68;
}
.notify-demo-heading {
  font-size: clamp(1.4rem, 3vw, 1.9rem);
  line-height: 1.25;
  font-weight: 500;
  letter-spacing: -0.035em;
}
.notify-demo-description {
  max-width: 45rem;
  color: #5f5763;
  line-height: 1.7;
}
.notify-demo p {
  margin: 0;
}
.notify-demo-field {
  display: grid;
  gap: 0.5rem;
  min-width: 0;
  max-width: 28rem;
  color: #5f5763;
  font-size: 0.8125rem;
}
.notify-demo-field input {
  display: block;
  box-sizing: border-box;
  min-width: 0;
  width: 100%;
  min-height: 3.125rem;
  padding: 0.75rem 1rem;
  font:
    400 1rem/1.5 system-ui,
    sans-serif;
  color: #26232b;
  background: #f4f2f7;
  border: 0.0625rem solid #b7adb9;
  border-radius: 0.5rem;
}
.notify-demo-field input {
  cursor: text;
}
.notify-demo-field input:disabled {
  opacity: 0.5;
  cursor: not-allowed;
}
@media (hover: hover) {
  .notify-demo-field input:enabled:hover {
    border-color: #8d7a98;
  }
}
.notify-demo-result {
  min-height: 1.5rem;
  font-size: 0.8125rem;
  color: #5f5763;
}
.notify-demo-actions {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 0.625rem;
  padding-top: 0.5rem;
}
.notify-demo-actions button {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  box-sizing: border-box;
  min-height: 3.125rem;
  padding: 0.5rem 1.4rem;
  font:
    500 0.875rem/1.5 system-ui,
    sans-serif;
  letter-spacing: -0.01em;
  cursor: pointer;
  border: 0.0625rem solid #b7adb9;
  border-radius: 0.875rem;
  color: #26232b;
  background: #f4f2f7;
}
.notify-demo-actions [data-demo-action] {
  background: #b45309;
  border-color: transparent;
  color: #fff;
}
.notify-demo-actions [data-demo-reset] {
  min-height: 2.5rem;
  padding-inline: 1rem;
  border-radius: 624.9375rem;
  color: #5f5763;
  border-color: #b7adb9;
  background: transparent;
}
.notify-demo-actions button:disabled {
  opacity: 0.5;
  cursor: not-allowed;
}
@media (hover: hover) {
  .notify-demo-actions button:enabled:hover {
    background: #e8e5ed;
    border-color: #8d7a98;
  }
  .notify-demo-actions [data-demo-action]:enabled:hover {
    background: #92400e;
    border-color: transparent;
  }
  .notify-demo-actions [data-demo-reset]:enabled:hover {
    color: #b45309;
    background: #fef3c7;
  }
}
.notify-demo :focus-visible {
  outline: 0.125rem solid #b45309;
  outline-offset: 0.1875rem;
}
.notify-demo [hidden] {
  display: none;
}
.notify-demo-actions button {
  overflow-wrap: anywhere;
  max-width: 100%;
}
main.js
import { browser as notify } from '@samline/notify'
import '@samline/notify/style.css'
import './style.css'

const copy = { saving: 'Saving your profile…', saved: 'Profile saved' }

const saveDemo = (element, notify, copy, signal) => {
  const input = element.querySelector('input')
  const action = element.querySelector('[data-demo-action]')
  const result = element.querySelector('[data-demo-result]')
  const initial = result.textContent
  let pending = new AbortController()

  action.addEventListener(
    'click',
    () => {
      const name = input.value.trim()
      if (!name) return input.reportValidity()

      notify.createToaster({ richColors: true, closeButton: true })
      action.disabled = true
      const saving = wait(1200, pending.signal).then(done => {
        if (!done) throw new DOMException('Reset', 'AbortError')
        return name
      })
      notify.toast.promise(saving, {
        loading: copy.saving,
        success: saved => {
          result.textContent = `${copy.saved}: ${saved}`
          action.disabled = false
          return { message: copy.saved, description: saved }
        },
      })
    },
    { signal }
  )

  element.querySelector('[data-demo-reset]').addEventListener(
    'click',
    () => {
      pending.abort()
      pending = new AbortController()
      notify.toast.dismiss()
      action.disabled = false
      result.textContent = initial
    },
    { signal }
  )
}

// Resolves true after `ms`, or false as soon as `signal` aborts.
const wait = (ms, signal) =>
  new Promise(resolve => {
    const timer = setTimeout(resolve, ms, true)
    signal.addEventListener(
      'abort',
      () => {
        clearTimeout(timer)
        resolve(false)
      },
      { once: true }
    )
  })

saveDemo(document.querySelector('[data-notify-demo]'), notify, copy)

// A page that is leaving no longer needs its toaster.
window.addEventListener('pagehide', event => {
  if (!event.persisted) notify.destroyToaster()
})
index.html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>A save worth confirming</title>

    <style>
      /* Demo form only. Toast appearance and motion come from @samline/notify/style.css. */
      .notify-demo {
        display: grid;
        gap: 1rem;
        min-width: 0;
        color: #26232b;
      }
      .notify-demo-eyebrow {
        font: 0.625rem/1.6 monospace;
        letter-spacing: 0.12em;
        text-transform: uppercase;
        color: #655d68;
      }
      .notify-demo-heading {
        font-size: clamp(1.4rem, 3vw, 1.9rem);
        line-height: 1.25;
        font-weight: 500;
        letter-spacing: -0.035em;
      }
      .notify-demo-description {
        max-width: 45rem;
        color: #5f5763;
        line-height: 1.7;
      }
      .notify-demo p {
        margin: 0;
      }
      .notify-demo-field {
        display: grid;
        gap: 0.5rem;
        min-width: 0;
        max-width: 28rem;
        color: #5f5763;
        font-size: 0.8125rem;
      }
      .notify-demo-field input {
        display: block;
        box-sizing: border-box;
        min-width: 0;
        width: 100%;
        min-height: 3.125rem;
        padding: 0.75rem 1rem;
        font:
          400 1rem/1.5 system-ui,
          sans-serif;
        color: #26232b;
        background: #f4f2f7;
        border: 0.0625rem solid #b7adb9;
        border-radius: 0.5rem;
      }
      .notify-demo-field input {
        cursor: text;
      }
      .notify-demo-field input:disabled {
        opacity: 0.5;
        cursor: not-allowed;
      }
      @media (hover: hover) {
        .notify-demo-field input:enabled:hover {
          border-color: #8d7a98;
        }
      }
      .notify-demo-result {
        min-height: 1.5rem;
        font-size: 0.8125rem;
        color: #5f5763;
      }
      .notify-demo-actions {
        display: flex;
        flex-wrap: wrap;
        align-items: center;
        gap: 0.625rem;
        padding-top: 0.5rem;
      }
      .notify-demo-actions button {
        display: inline-flex;
        align-items: center;
        justify-content: center;
        box-sizing: border-box;
        min-height: 3.125rem;
        padding: 0.5rem 1.4rem;
        font:
          500 0.875rem/1.5 system-ui,
          sans-serif;
        letter-spacing: -0.01em;
        cursor: pointer;
        border: 0.0625rem solid #b7adb9;
        border-radius: 0.875rem;
        color: #26232b;
        background: #f4f2f7;
      }
      .notify-demo-actions [data-demo-action] {
        background: #b45309;
        border-color: transparent;
        color: #fff;
      }
      .notify-demo-actions [data-demo-reset] {
        min-height: 2.5rem;
        padding-inline: 1rem;
        border-radius: 624.9375rem;
        color: #5f5763;
        border-color: #b7adb9;
        background: transparent;
      }
      .notify-demo-actions button:disabled {
        opacity: 0.5;
        cursor: not-allowed;
      }
      @media (hover: hover) {
        .notify-demo-actions button:enabled:hover {
          background: #e8e5ed;
          border-color: #8d7a98;
        }
        .notify-demo-actions [data-demo-action]:enabled:hover {
          background: #92400e;
          border-color: transparent;
        }
        .notify-demo-actions [data-demo-reset]:enabled:hover {
          color: #b45309;
          background: #fef3c7;
        }
      }
      .notify-demo :focus-visible {
        outline: 0.125rem solid #b45309;
        outline-offset: 0.1875rem;
      }
      .notify-demo [hidden] {
        display: none;
      }
      .notify-demo-actions button {
        overflow-wrap: anywhere;
        max-width: 100%;
      }
    </style>
  </head>
  <body>
    <main
      style="max-width: 48rem; margin: 2rem auto; padding: 1rem; font-family: system-ui, sans-serif"
    >
      <section
        class="notify-demo"
        data-notify-demo
        data-preset="save"
        aria-label="Profile settings"
      >
        <p class="notify-demo-eyebrow">Profile settings</p>
        <strong class="notify-demo-heading">A little more like you.</strong>
        <p class="notify-demo-description">
          Update your public display name. Nothing leaves this page.
        </p>
        <label class="notify-demo-field"
          >Display name<input
            type="text"
            value="Nora Quinn"
            required
            maxlength="60"
            autocomplete="name"
        /></label>

        <p class="notify-demo-result" data-demo-result role="status">Your profile is up to date.</p>
        <div class="notify-demo-actions">
          <button type="button" data-demo-action>Save changes</button>

          <button type="button" data-demo-reset>Reset this preview</button>
        </div>
      </section>
    </main>

    <script type="module">
      import { browser as notify } from '@samline/notify'
      import '@samline/notify/style.css'

      const copy = { saving: 'Saving your profile…', saved: 'Profile saved' }

      const saveDemo = (element, notify, copy, signal) => {
        const input = element.querySelector('input')
        const action = element.querySelector('[data-demo-action]')
        const result = element.querySelector('[data-demo-result]')
        const initial = result.textContent
        let pending = new AbortController()

        action.addEventListener(
          'click',
          () => {
            const name = input.value.trim()
            if (!name) return input.reportValidity()

            notify.createToaster({ richColors: true, closeButton: true })
            action.disabled = true
            const saving = wait(1200, pending.signal).then(done => {
              if (!done) throw new DOMException('Reset', 'AbortError')
              return name
            })
            notify.toast.promise(saving, {
              loading: copy.saving,
              success: saved => {
                result.textContent = `${copy.saved}: ${saved}`
                action.disabled = false
                return { message: copy.saved, description: saved }
              },
            })
          },
          { signal }
        )

        element.querySelector('[data-demo-reset]').addEventListener(
          'click',
          () => {
            pending.abort()
            pending = new AbortController()
            notify.toast.dismiss()
            action.disabled = false
            result.textContent = initial
          },
          { signal }
        )
      }

      // Resolves true after `ms`, or false as soon as `signal` aborts.
      const wait = (ms, signal) =>
        new Promise(resolve => {
          const timer = setTimeout(resolve, ms, true)
          signal.addEventListener(
            'abort',
            () => {
              clearTimeout(timer)
              resolve(false)
            },
            { once: true }
          )
        })

      saveDemo(document.querySelector('[data-notify-demo]'), notify, copy)

      // A page that is leaving no longer needs its toaster.
      window.addEventListener('pagehide', event => {
        if (!event.persisted) notify.destroyToaster()
      })
    </script>
  </body>
</html>

The lifecycle

  1. Mount. createToaster(options?) creates the ol container, applies the data attributes and the CSS custom properties the stylesheet reads, and subscribes to the shared observer.
  2. Toast. toast(message, options?) and its variants push a record into the observer. The renderer reconciles a list item for that id.
  3. Update. toaster.update(options?) re-applies the container attributes and variables. Omitted options keep their current value.
  4. Resolve. toast.promise(input, data?) ties a loading toast to a success or error toast on the same id.
  5. Dismiss. Toasts auto-dismiss after their duration. toast.dismiss(id) ends one early, toast.dismiss() ends them all.
  6. Destroy. destroyToaster() unmounts the container, clears every timer, and clears the singleton. Nothing remounts it for you — call createToaster() again when you need it back.

Next steps

For the observer, DOM attributes, method side effects and advanced direct mounts, read the Runtime contract.