Skip to main content

​
Vanilla JS SDK

The @notifizz/vanilla package provides a framework-agnostic API to embed the Notifizz Notification Center in any web application — no React, Angular, or other framework required.

​
Installation

npm install @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

OptionTypeRequiredDefaultDescription
apiKeystringYes—Your Front API Key.
authType'firebase' | 'backendToken' | 'none'Yes—Authentication strategy.
tokenstringConditional—Required for firebase and backendToken.
userIdstringConditional—Required for backendToken and none.
userEmailstringConditional—Required for backendToken and none.
positionNotifizzPositionNo—Bell position.
notificationCenterStyles{ marginTop?: string }No—Notification center style overrides.
bellStyles{ marginRight?: string; marginLeft?: string }No—Bell style overrides.
serverUrlstringNo"https://widget.notifizz.com"Widget server URL.
apiUrlstringNo"https://eu.api.notifizz.com/v1"API base URL.
widgetPathstringNo"/v1/widget.js"Widget script path.
mountIdstringNo"notifizz-notifications"DOM element ID for the mount point.
Returns: NotifizzVanillaApi — the instance API described below.

​
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);
ParameterTypeRequiredDescription
elementHTMLElementNoTarget DOM element. Created automatically if omitted.
Returns: HTMLElement — the mounted element.

​
getState()

Returns a copy of the current widget state. 
const state = notifizz.getState();
console.log(state.unreadCount); // 3
console.log(state.isOpen);      // false
Returns: NotifizzState
PropertyTypeDescription
isReadybooleanWhether the widget has loaded.
isOpenbooleanWhether the notification center is open.
unreadCountnumberCurrent unread count.
lastUpdatednumberTimestamp of last update.
hasErrorboolean?Error flag.
errorCodestring?Error code.

​
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 is ready!");
});

// Later, to stop listening:
unsubscribe();
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("Is open:", ctx.isOpen);
});
The callback receives a NotifizzBellContext:
PropertyTypeDescription
unreadCountnumberCurrent unread count.
isOpenbooleanWhether the notification center is open.
isReadybooleanWhether the widget is ready.
toggle() => voidToggle the notification center.
open() => voidOpen the notification center.
close() => voidClose the notification center.
Returns: () => void — an unsubscribe function.

​
open()

Opens the notification center. 
notifizz.open();

​
close()

Closes the notification center. 
notifizz.close();

​
toggle()

Toggles the notification center open or closed. 
notifizz.toggle();

​
setBellElement(element)

Sets a custom HTML element as the bell. The SDK automatically adds a click listener (to toggle) and sets a data-unread attribute 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>
ParameterTypeDescription
elementHTMLElement | nullThe custom bell element. Pass null to remove.

​
destroy()

Removes the widget from the DOM and cleans up all event listeners.
This is a one-way operation — you cannot reuse the instance after calling destroy(). Create a new instance with createNotifizz() if you need the widget again.
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();

    // Use a custom bell element
    const bell = document.getElementById("notif-bell");
    notifizz.setBellElement(bell);

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

​
Exported types

The following types can be imported from @notifizz/vanilla:
TypeDescription
NotifizzStateWidget state object (isReady, isOpen, unreadCount, lastUpdated, hasError?, errorCode?).
NotifizzPositionPosition union: 'top-right', 'top-left', 'bottom-right', 'bottom-left'.
NotifizzBellContextBell context with state + controls (unreadCount, isOpen, isReady, toggle, open, close).
NotifizzOptionsOptions passed to createNotifizz().
NotifizzVanillaApiThe instance API returned by createNotifizz().
NotifizzConfigInternal configuration (apiKey, apiUrl, serverUrl, widgetPath).

​
Next steps

Frontend quickstart

Get started with a complete example in under 5 minutes.

Shared concepts

Positioning, styling, state model, and widget lifecycle.