A lightweight, dependency-friendly wrapper around the browser Notification API. It gives you a clean, reactive (RxJS) and Promise-based API for requesting permission, showing notifications, auto-dismissing them, delaying them, and reacting to click/close/show events.

👉 Try the live demo — request permission and fire real notifications right from your browser.

Note: This library wraps the Notification API (the small banner/toast notifications a page can show while it is open). It does not implement the Push API or service-worker push, so it does not deliver messages while the site is closed. If you only need to notify the user while your app is running, this is for you.

• 🔔 Show browser notifications with the full set of native options.
• ⏱️ Auto-dismiss notifications after a configurable timeout.
• ⏳ Delay a notification before it is shown.
• 🖱️ Handle click, close, show, error and permission-denied events via callbacks.
• 🛡️ Graceful permission handling — never prompts twice, never throws on unsupported browsers.
• 🧩 Use it your way: RxJS Observables (show) or Promises (showAsync).
• 🪶 Tiny, tree-shakeable ESM/CJS builds plus a ready-to-use UMD bundle for CDNs.
• 📘 Written in TypeScript with complete type definitions.

npm install @andreasnicolaou/web-notifier

rxjs (v7+) is a dependency. If your app already uses RxJS, it is deduped automatically.

import { WebPushNotifier } from '@andreasnicolaou/web-notifier';

const notifier = new WebPushNotifier({ autoDismiss: 5000 });

const notification = await notifier.showAsync('Hello there!', {
  body: 'This is a test notification using @andreasnicolaou/web-notifier.',
});

if (notification) {
  console.log('Notification shown!');
}

import { WebPushNotifier } from '@andreasnicolaou/web-notifier';

const notifier = new WebPushNotifier({ autoDismiss: 5000 });

notifier
  .show('Hello there!', { body: 'Reactive notification.' }, { onclick: () => console.log('clicked') })
  .subscribe((notification) => {
    if (notification) {
      console.log('Notification shown!');
    }
  });

You can also fire-and-forget — calling show() displays the notification immediately, even without subscribing:

notifier.show('Quick ping!');

if (WebPushNotifier.isSupported()) {
  const notifier = new WebPushNotifier();
  notifier.requestPermission().subscribe((permission) => {
    console.log('Permission is now:', permission); // 'granted' | 'denied' | 'default'
  });
}

You can use the library directly in the browser via CDN. The UMD build exposes the global variable webNotifier.

<script src="https://unpkg.com/@andreasnicolaou/web-notifier"></script>
<script>
  const Notifier = window.webNotifier.WebPushNotifier;
  const notifier = new Notifier({ autoDismiss: 2000 });
  notifier.show('Hello from CDN!', { body: 'This is a test notification.' });
</script>

Other CDN entry points:

• unpkg (minified): https://unpkg.com/@andreasnicolaou/web-notifier/dist/index.umd.min.js
• jsDelivr (unminified): https://cdn.jsdelivr.net/npm/@andreasnicolaou/web-notifier/dist/index.umd.js
• jsDelivr (minified): https://cdn.jsdelivr.net/npm/@andreasnicolaou/web-notifier/dist/index.umd.min.js

Creates a notifier. globalOptions and globalCallbacks are merged into (and overridden by) the per-call options/callbacks passed to show / showAsync.

Shows a notification. Returns a shared Observable that emits the Notification instance (or null if permission was not granted). The notification is created exactly once, no matter how many times you subscribe.

Promise-based variant of show. Resolves with the Notification instance, or null when permission is not granted. Rejects if notifications are unsupported.

Requests permission, returning the existing value without re-prompting if it has already been granted or denied.

Closes all notifications created by this instance that are still open.

Returns whether the current environment supports the Notification API (available as both an instance and a static method).

The current permission, or 'unsupported' when the API is unavailable.

The number of notifications from this instance that are currently open.

Extends the native NotificationOptions with:

These come from the underlying Notification API, not from this library:

• The OS controls display. Your operating system decides how many notifications are visible at once and may queue or coalesce them — that is expected, not a bug.
• activeCount / dismissAll are best-effort. They track notifications this instance created and was told were closed. Some browsers (notably Chrome on Windows) fire the close event unreliably, so a notification the user closes from the OS may remain counted until you call dismissAll(). For deterministic cleanup, use the autoDismiss option — the library closes those itself and updates its tracking regardless of the close event.
• Permission must be requested from a user gesture (e.g. a click handler) in modern browsers.

• Notification API - MDN
• Browser Compatibility - MDN

MIT © Andreas Nicolaou