`@notifizz/vanilla` SDK reference

@notifizz/vanilla is the framework-agnostic SDK for the Notifizz Notification Center widget. Use it from plain JavaScript, Vue, Svelte, server-rendered pages with islands, or any setup that isn’t already covered by @notifizz/react or @notifizz/angular.

TL;DR

createNotifizz(options) returns a NotifizzVanillaApi — call mount() to attach the bell to the DOM.
Three auth modes via authType: 'firebase', 'backendToken', 'none' (dev-only).
Subscribe to changes with onStateChange(cb); read state synchronously with getState().
Replace the default bell with setBellElement(el) — the SDK handles click + keeps a data-unread attribute in sync.
Web push opt-in is headless: webpushOptIn() / webpushOptOut() plus getWebPushStatus() let you own the button.

Installation

npm install @notifizz/vanilla

yarn add @notifizz/vanilla

pnpm add @notifizz/vanilla

`createNotifizz(options)`

Creates a new Notifizz instance. This is the entry point for the SDK.

import { createNotifizz } from "@notifizz/vanilla";

const notifizz = createNotifizz({
  apiKey: "YOUR_FRONT_API_KEY",
  authType: "backendToken",
  token: "TOKEN_FROM_BACKEND",
  userId: "user_42",
  userEmail: "alice@example.com",
  position: "top-right",
});

Options

Option	Type	Required	Default	Description
`apiKey`	`string`	yes	—	Your Front API Key.
`authType`	`'firebase' \| 'backendToken' \| 'none'`	yes	—	Authentication strategy.
`token`	`string`	for `firebase`, `backendToken`	—	Auth token from your backend.
`userId`	`string`	for `backendToken`, `none`	—	The user’s unique identifier.
`userEmail`	`string`	for `backendToken`, `none`	—	The user’s email address.
`position`	`NotifizzPosition`	no	—	Bell position.
`notificationCenterStyles`	`{ marginTop?: string }`	no	—	Notification center style overrides.
`bellStyles`	`{ marginRight?: string; marginLeft?: string }`	no	—	Bell style overrides.
`serverUrl`	`string`	no	`https://widget.notifizz.com`	Widget server URL.
`apiUrl`	`string`	no	`https://api.notifizz.com/v1`	API base URL.
`widgetPath`	`string`	no	`/v1/widget.js`	Widget script path.
`mountId`	`string`	no	`notifizz-notifications`	DOM id for the mount point.

Returns — NotifizzVanillaApi, the instance API described below.

`authType: "none"` example (dev only)

const notifizz = createNotifizz({
  apiKey: "YOUR_FRONT_API_KEY",
  authType: "none",
  userId: "dev_user_42",
  userEmail: "dev@example.com",
});

notifizz.mount();

authType: "none" ships unauthenticated widget access — anyone with the apiKey can read any user’s inbox. Use it for local development only. Production must use firebase or backendToken.

Instance methods

`mount(element?)`

Mounts the widget to the DOM. If no element is provided, creates a <div> and appends it to document.body.

// Auto-mount to body
notifizz.mount();

// Mount to a specific element
const container = document.getElementById("my-notifications");
notifizz.mount(container);

Parameter	Type	Required	Description
`element`	`HTMLElement`	no	Target DOM element. Created automatically if omitted.

Returns — HTMLElement, the mounted element.

`getState()`

Synchronous snapshot of the current widget state.

const state = notifizz.getState();
console.log(state.unreadCount); // 3
console.log(state.isOpen);      // false

Returns — NotifizzState:

Property	Type	Description
`isReady`	`boolean`	`true` once the widget has loaded and authenticated.
`isOpen`	`boolean`	`true` when the dropdown is open.
`unreadCount`	`number`	Current unread count.
`lastUpdated`	`number`	Timestamp (ms) of the last state change.
`hasError`	`boolean?`	`true` if the widget hit an auth or network error.
`errorCode`	`string?`	Error identifier when `hasError` is `true`.
`webpushStatus`	`WebPushStatus?`	Web push opt-in status in this browser: `unsupported`, `unavailable`, `ready`, `subscribed`, `denied`. Absent until the widget has booted web push for the signed-in user.

`onReady(callback)`

Registers a callback that fires when the widget is ready. If the widget is already ready, the callback fires immediately.

const unsubscribe = notifizz.onReady(() => {
  console.log("widget ready");
});

unsubscribe(); // stop listening

Returns — () => void, an unsubscribe function.

`onStateChange(callback)`

Registers a callback that fires on every state change.

const unsubscribe = notifizz.onStateChange((state) => {
  document.title = state.unreadCount > 0
    ? `(${state.unreadCount}) My App`
    : "My App";
});

Returns — () => void, an unsubscribe function.

`onBellUpdate(callback)`

Registers a callback that fires when the bell context updates (unread count, open state).

const unsubscribe = notifizz.onBellUpdate((ctx) => {
  console.log("unread:", ctx.unreadCount);
  console.log("isOpen:", ctx.isOpen);
});

The callback receives a NotifizzBellContext:

Property	Type	Description
`unreadCount`	`number`	Current unread count.
`isOpen`	`boolean`	Whether the dropdown is open.
`isReady`	`boolean`	Whether the widget is ready.
`toggle`	`() => void`	Toggle the dropdown.
`open`	`() => void`	Open the dropdown.
`close`	`() => void`	Close the dropdown.
`webpush`	`NotifizzWebPush`	Headless web push surface for a custom bell: `{ status, optIn(), optOut() }`. See web push opt-in.

Returns — () => void, an unsubscribe function.

`open()` / `close()` / `toggle()`

Drive the dropdown programmatically.

notifizz.open();
notifizz.close();
notifizz.toggle();

Web push opt-in

Closed beta. Web push is enabled per organisation and is off by default. Until it is switched on for yours, no campaign can take a push step — so an opt-in collected here would have nothing to deliver. Ask your Notifizz contact to switch it on. Campaigns that already carry a push step keep sending either way.

Three members drive the browser subscription without any Notifizz UI — you own the button and its timing.

Member	Returns	Description
`webpushOptIn()`	`void`	Trigger the browser permission prompt and subscribe this browser. Call it from a real user gesture.
`webpushOptOut()`	`void`	Drop and revoke this browser’s subscription.
`getWebPushStatus()`	`WebPushStatus`	Synchronous snapshot. The same value is on `getState().webpushStatus` and on the bell context.

const button = document.getElementById("enable-notifications");

button.addEventListener("click", () => notifizz.webpushOptIn());

// Keep the button in sync with the reactive status.
notifizz.onStateChange((state) => {
  button.disabled = state.webpushStatus !== "ready";
});

Status	Meaning	Your button
`unavailable`	The environment has no push key yet, or the service worker isn’t served	Hide it
`unsupported`	The browser can’t do web push	Hide it
`ready`	Configured, and the user hasn’t decided	Enable it
`subscribed`	Already on	Offer `webpushOptOut()`
`denied`	The user blocked the browser permission	Hide it — only the user can undo this

The status starts at unavailable and settles once the widget has booted web push for the signed-in user, so read it from onStateChange (or onBellUpdate) rather than once at mount time. Full channel behaviour is in web push.

`setBellElement(element)`

Sets a custom HTML element as the bell. The SDK adds a click listener that toggles the dropdown and keeps a data-unread attribute in sync with the current count.

const myBell = document.getElementById("my-bell");
notifizz.setBellElement(myBell);

<button id="my-bell">
  Notifications <span class="badge"></span>
</button>

<style>
  /* Style based on the data-unread attribute */
  #my-bell[data-unread="0"] .badge { display: none; }
  #my-bell .badge::after { content: attr(data-unread); }
</style>

Parameter	Type	Description
`element`	`HTMLElement \| null`	The custom bell element. Pass `null` to remove.

`destroy()`

Removes the widget from the DOM and cleans up all event listeners.

destroy() is one-way — you cannot reuse the instance afterwards. Call createNotifizz(...) again for a fresh instance.

notifizz.destroy();

Full example

<!DOCTYPE html>
<html>
<head>
  <title>Notifizz Vanilla example</title>
</head>
<body>
  <header>
    <h1>My App</h1>
    <button id="notif-bell">Notifications</button>
  </header>

  <script type="module">
    import { createNotifizz } from "@notifizz/vanilla";

    const notifizz = createNotifizz({
      apiKey: "YOUR_FRONT_API_KEY",
      authType: "backendToken",
      token: "TOKEN_FROM_BACKEND",
      userId: "user_42",
      userEmail: "alice@example.com",
    });

    notifizz.mount();

    const bell = document.getElementById("notif-bell");
    notifizz.setBellElement(bell);

    notifizz.onStateChange((state) => {
      document.title = state.unreadCount > 0
        ? `(${state.unreadCount}) My App`
        : "My App";
    });
  </script>
</body>
</html>

Exported types

import type {
  NotifizzState,
  NotifizzPosition,
  NotifizzBellContext,
  NotifizzWebPush,
  WebPushStatus,
  NotifizzOptions,
  NotifizzVanillaApi,
} from "@notifizz/vanilla";

FAQ

Can I use this SDK from Vue / Svelte / Solid / etc?

Yes — the vanilla SDK is framework-agnostic by design. Mount the widget in the framework’s lifecycle hook (onMounted, onMount, useEffect-equivalent) and destroy() in the teardown. The state callbacks plug into any reactive store.

The widget mounted but the bell is not visible.

`getState()` returns `isReady: false` immediately after `createNotifizz`.

Expected — createNotifizz() doesn’t load the script synchronously. Call mount() first, then either await onReady() or check state.isReady in onStateChange.

My custom bell click does nothing.

setBellElement(el) overrides the default bell. If you registered your own click handler before calling it, the SDK still adds its listener — but your handler may stop the event with preventDefault / stopPropagation. Either rely on the SDK’s click handler, or attach yours after setBellElement and don’t stop propagation.

Where do `onStateChange` callbacks get called from?

The widget posts state changes via the notifizz:state window event. The SDK subscribes to that event once and fans out to your callbacks — there is no polling. State changes happen on the client, off the real-time stream listener.

How do I switch user?

Call destroy() on the current instance, then createNotifizz(...) with the new userId + token, then mount(). The widget caches real-time state per session, so without destroy the new mount briefly shows the previous user’s notifications.

Notification Center overview

Lifecycle, state model, positioning, custom bell.

Authentication overview

Pick the right widget auth mode.

Frontend quickstart

Get the widget rendering in under five minutes.

Backend quickstart

Send the events the widget will display.

Get started

Concepts

Use cases

SDKs

AI & MCP

Environments

Plans & usage

Monitor delivery

Glossary

@notifizz/vanilla SDK Reference

`@notifizz/vanilla` SDK reference

TL;DR

Installation

`createNotifizz(options)`

Options

`authType: "none"` example (dev only)

Instance methods

`mount(element?)`

`getState()`

`onReady(callback)`

`onStateChange(callback)`

`onBellUpdate(callback)`

`open()` / `close()` / `toggle()`

Web push opt-in

`setBellElement(element)`

`destroy()`

Full example

Exported types

FAQ

See also

Notification Center overview

Authentication overview

Frontend quickstart

Backend quickstart

​@notifizz/vanilla SDK reference

​TL;DR

​Installation

​createNotifizz(options)

​Options

​authType: "none" example (dev only)

​Instance methods

​mount(element?)

​getState()

​onReady(callback)

​onStateChange(callback)

​onBellUpdate(callback)

​open() / close() / toggle()

​Web push opt-in

​setBellElement(element)

​destroy()

​Full example

​Exported types

​FAQ

​See also

Notification Center overview

Authentication overview

Frontend quickstart

Backend quickstart

`@notifizz/vanilla` SDK reference

TL;DR

Installation

`createNotifizz(options)`

Options

`authType: "none"` example (dev only)

Instance methods

`mount(element?)`

`getState()`

`onReady(callback)`

`onStateChange(callback)`

`onBellUpdate(callback)`

`open()` / `close()` / `toggle()`

Web push opt-in

`setBellElement(element)`

`destroy()`

Full example

Exported types

FAQ

See also