Guide

Framework integrations

Use the vanilla Notify controller safely from React, Vue, Svelte, and server-rendered applications.

@samline/notify is a vanilla DOM package. It does not export a React component, a Vue plugin, a Svelte component, or a framework-specific context. Toaster is a function alias of createToaster().

Import the stylesheet once, mount the singleton from client lifecycle code, and use the exported toast object from event handlers or application services.

React

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

export function Notifications() {
  useEffect(() => {
    createToaster({ position: 'bottom-right' })
    return () => destroyToaster()
  }, [])

  return (
    <button type="button" onClick={() => toast.success('Saved')}>
      Save
    </button>
  )
}

Mount this integration once near the client root. React Strict Mode may run the development effect setup and cleanup cycle more than once; creating and destroying the singleton is safe, but destruction publishes dismissals. Avoid mounting the effect in multiple layout branches.

Vue

<script setup lang="ts">
import { onMounted, onUnmounted } from 'vue'
import { createToaster, destroyToaster, toast } from '@samline/notify'
import '@samline/notify/style.css'

onMounted(() => createToaster({ position: 'bottom-right' }))
onUnmounted(() => destroyToaster())

function save() {
  toast.success('Saved')
}
</script>

<template>
  <button type="button" @click="save">Save</button>
</template>

Use a single root or layout component rather than installing one toaster per view.

Svelte

<script lang="ts">
  import { onMount } from 'svelte'
  import { createToaster, destroyToaster, toast } from '@samline/notify'
  import '@samline/notify/style.css'

  onMount(() => {
    createToaster({ position: 'bottom-right' })
    return destroyToaster
  })
</script>

<button type="button" onclick={() => toast.success('Saved')}>Save</button>

onMount does not run during server rendering, which keeps DOM mounting on the client.

SSR and hydration

The root entrypoint and the browser registry are safe to import without a DOM. Mounting is not: createToaster() requires a DOM and a ready document.body, and mountToaster() requires a DOM and an explicit root.

For Astro, Next.js, Nuxt, SvelteKit, and similar systems:

  • import the CSS through the framework’s supported client or global stylesheet path,
  • call createToaster() in client-only lifecycle code,
  • avoid calling toast.* during server rendering, because state created on the server has no client renderer and should not be shared between requests,
  • destroy only when the application actually tears down the integration, then remount explicitly if client navigation needs it again.

Shared state, not channels

Do not create one direct mount per framework subtree. mountToaster() defaults to the global ToastState, so every such renderer receives the same events and can display duplicates. The legacy id and toasterId fields filter that shared stream; they do not isolate state, history, counters, or subscriptions, and they should not be treated as framework routing.

If an application truly needs independently owned notification systems, use separate package instances or build contexts, or design an advanced integration with an injected state object.

Complete integration files

Mount the framework component once near the client root. React Strict Mode can repeat setup and cleanup in development; the root owns the singleton. Avoid competing owners that destroy a toaster still in use elsewhere.

Notifications.tsx
import { useEffect } from 'react'
import { createToaster, destroyToaster, toast } from '@samline/notify'
import '@samline/notify/style.css'

// Mount once at the application root, not once per route or button.
export function Notifications() {
  useEffect(() => {
    createToaster({ richColors: true, closeButton: true })
    return () => destroyToaster()
  }, [])
  return (
    <button type="button" onClick={() => toast.success('Changes saved')}>
      Save changes
    </button>
  )
}
Notifications.vue
<script setup lang="ts">
import { onMounted, onUnmounted } from 'vue'
import { createToaster, destroyToaster, toast } from '@samline/notify'
import '@samline/notify/style.css'
onMounted(() => {
  createToaster({ richColors: true, closeButton: true })
})
onUnmounted(() => destroyToaster())
</script>
<template>
  <button type="button" @click="toast.success('Changes saved')">Save changes</button>
</template>
Notifications.svelte
<script lang="ts">
  import { onMount } from 'svelte'
  import { createToaster, destroyToaster, toast } from '@samline/notify'
  import '@samline/notify/style.css'
  onMount(() => {
    createToaster({ richColors: true, closeButton: true })
    return () => destroyToaster()
  })
</script>
<button type="button" onclick={() => toast.success('Changes saved')}>Save changes</button>
Notifications.astro
<button type="button" data-notify-save>
  Save changes
</button>
<script>
  import { createToaster, destroyToaster, toast } from '@samline/notify'
  import '@samline/notify/style.css'
  let cleanup: (() => void) | undefined
  const mount = () => {
    cleanup?.()
    const buttons = document.querySelectorAll<HTMLButtonElement>('[data-notify-save]')
    if (!buttons.length) return
    const lifecycle = new AbortController()
    createToaster({ richColors: true, closeButton: true })
    buttons.forEach(button =>
      button.addEventListener('click', () => toast.success('Changes saved'), {
        signal: lifecycle.signal,
      })
    )
    cleanup = () => {
      lifecycle.abort()
      destroyToaster()
      cleanup = undefined
    }
  }
  document.addEventListener('astro:before-swap', () => cleanup?.())
  document.addEventListener('astro:page-load', mount)
  mount()
</script>
notify.liquid
{% comment %} Add these assets once in theme.liquid, before </body>, in this order. {% endcomment %}
{{ 'notify.css' | asset_url | stylesheet_tag }}
{{ 'notify.global.js' | asset_url | script_tag }}
{{ 'notify-hosts.js' | asset_url | script_tag }}

{% comment %} Section markup: the host script handles editor replacement/unload. {% endcomment %}
<section data-notify-host>
  <button type="button" data-notify-save>Save changes</button>
</section>
notify-hosts.js
// Include once after the Notify standalone script, preferably in the layout.
;(() => {
  const key = Symbol.for('samline.notify.host-integration')
  if (window[key]) return
  const notify = window.Notify
  const owners = new Map()
  const unloaded = new WeakSet()
  const mount = root => {
    if (owners.has(root) || unloaded.has(root)) return
    const lifecycle = new AbortController()
    notify.createToaster({ richColors: true, closeButton: true })
    root.querySelectorAll('[data-notify-save]').forEach(button => {
      button.addEventListener('click', () => notify.toast.success('Changes saved'), {
        signal: lifecycle.signal,
      })
    })
    owners.set(root, () => lifecycle.abort())
  }
  const refresh = () => {
    document.querySelectorAll('[data-notify-host]').forEach(mount)
    for (const [root, cleanup] of owners) {
      if (!root.isConnected) {
        cleanup()
        owners.delete(root)
      }
    }
    if (!owners.size) notify.destroyToaster()
  }
  const lifecycle = new AbortController()
  const observer = new MutationObserver(refresh)
  observer.observe(document.body, { childList: true, subtree: true })
  document.addEventListener(
    'shopify:section:load',
    event => {
      event.target.querySelectorAll('[data-notify-host]').forEach(root => unloaded.delete(root))
      if (event.target.matches('[data-notify-host]')) unloaded.delete(event.target)
      refresh()
    },
    { signal: lifecycle.signal }
  )
  document.addEventListener(
    'shopify:section:unload',
    event => {
      for (const [root, cleanup] of owners) {
        if (event.target.contains(root)) {
          unloaded.add(root)
          cleanup()
          owners.delete(root)
        }
      }
      if (!owners.size) notify.destroyToaster()
    },
    { signal: lifecycle.signal }
  )
  window.addEventListener(
    'pagehide',
    event => {
      if (event.persisted) return
      lifecycle.abort()
      observer.disconnect()
      owners.forEach(cleanup => cleanup())
      owners.clear()
      notify.destroyToaster()
      delete window[key]
    },
    { signal: lifecycle.signal }
  )
  window[key] = true
  refresh()
})()
notify.php
<?php
// In the theme's functions.php; use one enqueue per asset, not one per block.
add_action('wp_enqueue_scripts', static function () {
    $base = get_stylesheet_directory_uri() . '/assets/';
    wp_enqueue_style('notify', $base . 'notify.css', [], '4.0.0');
    wp_enqueue_script('notify', $base . 'notify.global.js', [], '4.0.0', true);
    wp_enqueue_script('notify-hosts', $base . 'notify-hosts.js', ['notify'], '1.0.0', true);
});
?>
<!-- Block or template markup; the host script also handles DOM replacement. -->
<section data-notify-host>
  <button type="button" data-notify-save>Save changes</button>
</section>
notify-hosts.js
// Include once after the Notify standalone script, preferably in the layout.
;(() => {
  const key = Symbol.for('samline.notify.host-integration')
  if (window[key]) return
  const notify = window.Notify
  const owners = new Map()
  const unloaded = new WeakSet()
  const mount = root => {
    if (owners.has(root) || unloaded.has(root)) return
    const lifecycle = new AbortController()
    notify.createToaster({ richColors: true, closeButton: true })
    root.querySelectorAll('[data-notify-save]').forEach(button => {
      button.addEventListener('click', () => notify.toast.success('Changes saved'), {
        signal: lifecycle.signal,
      })
    })
    owners.set(root, () => lifecycle.abort())
  }
  const refresh = () => {
    document.querySelectorAll('[data-notify-host]').forEach(mount)
    for (const [root, cleanup] of owners) {
      if (!root.isConnected) {
        cleanup()
        owners.delete(root)
      }
    }
    if (!owners.size) notify.destroyToaster()
  }
  const lifecycle = new AbortController()
  const observer = new MutationObserver(refresh)
  observer.observe(document.body, { childList: true, subtree: true })
  document.addEventListener(
    'shopify:section:load',
    event => {
      event.target.querySelectorAll('[data-notify-host]').forEach(root => unloaded.delete(root))
      if (event.target.matches('[data-notify-host]')) unloaded.delete(event.target)
      refresh()
    },
    { signal: lifecycle.signal }
  )
  document.addEventListener(
    'shopify:section:unload',
    event => {
      for (const [root, cleanup] of owners) {
        if (event.target.contains(root)) {
          unloaded.add(root)
          cleanup()
          owners.delete(root)
        }
      }
      if (!owners.size) notify.destroyToaster()
    },
    { signal: lifecycle.signal }
  )
  window.addEventListener(
    'pagehide',
    event => {
      if (event.persisted) return
      lifecycle.abort()
      observer.disconnect()
      owners.forEach(cleanup => cleanup())
      owners.clear()
      notify.destroyToaster()
      delete window[key]
    },
    { signal: lifecycle.signal }
  )
  window[key] = true
  refresh()
})()

Astro navigation

The Astro component mounts native buttons after page load and cleans up before a client-side page swap. Include it in the root layout. Server rendering must not create toast state or mount a renderer.

Shopify and WordPress

Copy the matching published JavaScript and CSS assets into the theme as notify.global.js and notify.css. The CMS examples are pinned to 4.0.0. Add notify-hosts.js once after the package script. Shopify assets belong in the layout rather than being loaded once per section; WordPress dependency handles establish execution order.

Each data-notify-host scope owns its listeners. Multiple scopes share one toaster; removing the final owner destroys it. Shopify section load/unload and DOM replacement release the affected listeners. Do not use the preview’s saved message as proof of a server-side save: call the notification only after your real submission succeeds.

The Liquid and PHP files are integration fixtures, not certified deployments on a real store or WordPress installation. The shared host JavaScript is executed with multiple scopes, editor unload/reload and cleanup in Chromium; framework files are compiler checked locally.