Skip to main content

​
Widget bridge reference

The Notifizz widget exposes a programmatic command/event surface — BRIDGE_COMMANDS for sending instructions to the widget, BRIDGE_EVENTS for listening to its state. The three frontend SDKs (@notifizz/react, @notifizz/angular, @notifizz/vanilla) all wrap this same surface; this page documents it directly so you can integrate the widget from any runtime.

​
TL;DR

  • window.notifizz(command, ...args) — invoke a bridge command.
  • window.addEventListener("notifizz:ready", cb) — fires once when the widget is loaded and authenticated.
  • window.addEventListener("notifizz:state", cb) — fires on every state change with event.detail: NotifizzState.
  • The contract lives in sdk/shared/contract.ts — single source of truth for both the widget and every SDK.

​
Public commands

BRIDGE_COMMANDS are the public, supported instructions. They’re the same across React, Angular, and Vanilla.
CommandArgsDescription
authenticateWithFirebase{ apiKey, token, ...userFields? }Authenticate the widget session with a Firebase ID token.
authenticateWithBackendToken{ apiKey, token, userId, userEmail, ...additional? }Authenticate with an HMAC token minted server-side.
authenticateWithNone{ apiKey, userId, userEmail }Dev-only — no token verification.
setPosition'top-right' | 'top-left' | 'bottom-right' | 'bottom-left'Move the bell to one of four screen corners.
setNotificationCenterStyles{ marginTop?: string }Adjust the notification-center dropdown placement.
setBellStyles{ marginRight?: string; marginLeft?: string }Adjust bell placement.
togglenoneToggle the dropdown open/closed.
opennoneOpen the dropdown.
closenoneClose the dropdown.
getState(state: NotifizzState) => voidRead the current state synchronously via callback.
// Drive the widget directly from any runtime
window.notifizz("setPosition", "top-right");
window.notifizz("toggle");
window.notifizz("getState", (state) => console.log(state.unreadCount));
A few internal commands (e.g. setBellIcon, setRoundedButton) live in a separate internal registry and are not part of BRIDGE_COMMANDS. They’re used by the SDK packages and may change without notice — don’t call them from your code.

​
Public events

BRIDGE_EVENTS are dispatched on window:
EventPayload (event.detail)Description
notifizz:readynoneFires once when the widget is loaded and authenticated. After this, state.isReady === true.
notifizz:stateNotifizzStateFires on every state change. Subscribe to keep your UI in sync.
window.addEventListener("notifizz:ready", () => {
  console.log("widget ready");
});

window.addEventListener("notifizz:state", (e) => {
  const state = e.detail; // NotifizzState
  document.title = state.unreadCount > 0
    ? `(${state.unreadCount}) My App`
    : "My App";
});

​
NotifizzState

The state object delivered through notifizz:state and via the getState callback:
PropertyTypeDescription
isReadybooleantrue once the widget has loaded and authenticated.
isOpenbooleantrue when the dropdown is open.
unreadCountnumberCurrent unread notification count.
lastUpdatednumberTimestamp (ms) of the last state change.
hasErrorboolean?true if the widget hit an auth or network error.
errorCodestring?Error identifier when hasError is true.
The first four (STATE_FIELDS in the contract) are always present; hasError and errorCode appear only when the widget enters an error state.

​
Lifecycle ordering

A typical session flows like this:
Always wait for notifizz:ready (or check state.isReady) before sending commands like toggle / open / close. Commands sent before ready are dropped silently — the React/Angular/Vanilla SDKs already gate on this; if you build your own integration, do the same.

​
Building your own integration

If you need a framework Notifizz doesn’t ship a SDK for (Vue 3 with composables, Solid, Svelte 5, …), the bridge is enough. Minimal recipe:
  1. Inject the widget script (https://widget.notifizz.com/v1/widget.js) — use a <script> tag or your framework’s lifecycle hook.
  2. Wait until typeof window.notifizz === "function".
  3. Call window.notifizz("authenticateWith…", options) with your auth fields.
  4. Listen for notifizz:ready to know when the widget is live.
  5. Listen for notifizz:state to drive any UI you build around the widget.
  6. Call window.notifizz("toggle" | "open" | "close") from your own UI elements.
The vanilla SDK (sdk/front-end/notifizz-vanilla) is a clean reference implementation — about 200 lines of glue around this exact protocol.

​
FAQ

Call window.notifizz("toggle") (or "open") from your click handler. If you’re using a framework SDK, prefer its idiomatic API (useNotifizz().toggle in React, NotifizzService.toggle() in Angular, notifizz.toggle() in Vanilla) — they all delegate to the same bridge command.
Listen for notifizz:state and read state.unreadCount. Hide the default bell with CSS or by passing a custom render in your SDK (renderBell in React, #customBellIcon in Angular, setBellElement(el) in Vanilla).
Expected — authentication is async. Call getState from inside notifizz:ready, or wait for the first notifizz:state event whose detail.isReady === true.
Dropped silently. The widget queues authenticateWith… calls but not toggle / open / close. Always gate your commands on state.isReady to avoid surprises.
No — those are internal commands used by the SDK packages and not part of BRIDGE_COMMANDS. They may change without notice. If you need a custom bell, use the renderBell (React), content-projection (Angular), or setBellElement(el) (Vanilla) APIs — those go through the supported public surface.
No, the widget is a singleton bound to window.notifizz. To switch users, destroy the current instance (via your SDK’s destroy() method) and re-mount with new auth. Two simultaneous identities aren’t supported today.

​
See also

Notification Center overview

Lifecycle, state model, custom bell, headless mode.

React SDK

Idiomatic React wrapper around the bridge.

Vanilla JS SDK

Reference implementation of a bridge consumer.

Authentication overview

The four widget auth modes and when to pick each.