`@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.

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://eu.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`.

`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.

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

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

Drive the dropdown programmatically.

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

`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,
  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.

@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()`

`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()

​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()`

`setBellElement(element)`

`destroy()`

Full example

Exported types

FAQ

See also