`@notifizz/react` SDK reference

@notifizz/react ships the React components and hooks for the Notifizz Notification Center widget — a NotifizzInbox component for the default bell, a NotifizzProvider for app-wide state access, and a useNotifizz hook for reading state and driving the widget from any descendant.

TL;DR

<NotifizzInbox options={...} /> — drop-in component that renders the bell + dropdown and authenticates the widget.
<NotifizzProvider options={...}> + useNotifizz() — share notification state across the app via context, or build a fully headless UI.
Three auth modes via authType: 'firebase', 'backendToken', 'none' (dev-only).
renderBell prop replaces the default bell with your own UI; useNotifizz exposes unreadCount, isOpen, isReady, open, close, toggle.

Installation

npm install @notifizz/react

yarn add @notifizz/react

pnpm add @notifizz/react

Components

`NotifizzInbox`

Default component. Mounts the widget, renders the bell, and listens for notifizz:ready / notifizz:state window events.

import NotifizzInbox from "@notifizz/react";

function App() {
  return (
    <NotifizzInbox
      options={{
        apiKey: "YOUR_FRONT_API_KEY",
        authType: "backendToken",
        token: "TOKEN_FROM_BACKEND",
        userId: "user_42",
        userEmail: "alice@example.com",
        position: "top-right",
      }}
      onReady={() => console.log("widget ready")}
      onStateChange={(state) => console.log("unread:", state.unreadCount)}
    />
  );
}

Props

Prop	Type	Required	Default	Description
`options`	`NotifizzInboxOptions`	yes	—	Authentication and display options.
`renderBell`	`(ctx: NotifizzBellContext) => ReactNode`	no	`<DefaultBell />`	Custom bell render function.
`onReady`	`() => void`	no	—	Called once when the widget is ready.
`onStateChange`	`(state: NotifizzState) => void`	no	—	Called on every state change.
`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 widget mount point.

`NotifizzInboxOptions`

Option	Type	Required	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	`'top-right' \| 'top-left' \| 'bottom-right' \| 'bottom-left'`.
`notificationCenterStyles`	`{ marginTop?: string }`	no	Notification center style overrides.
`bellStyles`	`{ marginRight?: string; marginLeft?: string }`	no	Bell style overrides.

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

<NotifizzInbox
  options={{
    apiKey: "YOUR_FRONT_API_KEY",
    authType: "none",
    userId: "dev_user_42",
    userEmail: "dev@example.com",
  }}
/>

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.

`NotifizzProvider`

Wraps a subtree to provide notification state via React context. Use it when multiple components need access to notification state, or when you want a fully headless UI.

import { NotifizzProvider } from "@notifizz/react";

function App() {
  return (
    <NotifizzProvider
      options={{
        apiKey: "YOUR_FRONT_API_KEY",
        authType: "backendToken",
        token: "TOKEN_FROM_BACKEND",
        userId: "user_42",
        userEmail: "alice@example.com",
      }}
    >
      <YourApp />
    </NotifizzProvider>
  );
}

Prop	Type	Required	Description
`options`	`NotifizzInboxOptions`	yes	Authentication and display options.
`serverUrl`	`string`	no	Widget server URL.
`apiUrl`	`string`	no	API base URL.
`widgetPath`	`string`	no	Widget script path.
`mountId`	`string`	no	DOM id for the widget mount point.
`children`	`ReactNode`	yes	Subtree that gets context access.

Hooks

`useNotifizz()`

Read notification state and drive the widget from any component inside a NotifizzProvider.

import { useNotifizz } from "@notifizz/react";

function NotificationBadge() {
  const { unreadCount, isOpen, isReady, toggle } = useNotifizz();

  if (!isReady) return null;

  return (
    <button onClick={toggle}>
      Notifications {unreadCount > 0 && `(${unreadCount})`}
    </button>
  );
}

Return value: `NotifizzBellContext`

Property	Type	Description
`unreadCount`	`number`	Current unread notification count.
`isOpen`	`boolean`	Whether the notification center is open.
`isReady`	`boolean`	Whether the widget has loaded and authenticated.
`toggle`	`() => void`	Toggle the notification center.
`open`	`() => void`	Open the notification center.
`close`	`() => void`	Close the notification center.
`webpush`	`NotifizzWebPush`	Headless web push surface — `status`, `optIn()`, `optOut()`. See opt-in from your own UI.

useNotifizz() must be called from inside a NotifizzProvider. Calling it outside throws.

Custom bell

Replace the default bell with your own component using the renderBell prop:

<NotifizzInbox
  options={{ /* ... */ }}
  renderBell={(ctx) => (
    <div className="my-custom-bell" onClick={ctx.toggle}>
      <span className="bell-icon">🔔</span>
      {ctx.unreadCount > 0 && (
        <span className="badge">{ctx.unreadCount}</span>
      )}
    </div>
  )}
/>

The ctx object is the same NotifizzBellContext that useNotifizz() returns.

Headless mode

Headless mode gives you full control over the notification UI while Notifizz handles real-time data and state. Pair it with your design system for a fully bespoke notification surface.

Use NotifizzProvider + useNotifizz without rendering NotifizzInbox:

function App() {
  return (
    <NotifizzProvider options={{ /* ... */ }}>
      <CustomNotificationUI />
    </NotifizzProvider>
  );
}

function CustomNotificationUI() {
  const { unreadCount, isOpen, toggle } = useNotifizz();

  return (
    <div>
      <button onClick={toggle}>
        {isOpen ? "Hide" : "Show"} notifications ({unreadCount})
      </button>
    </div>
  );
}

State shape

NotifizzState (read via onStateChange or useNotifizz):

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

Exported types

import type {
  NotifizzInboxProps,
  NotifizzInboxOptions,
  NotifizzBellContext,
  NotifizzState,
  NotifizzWebPush,
  WebPushStatus,
} from "@notifizz/react";

FAQ

`useNotifizz()` throws 'must be used within a NotifizzProvider'.

The component calling useNotifizz() is rendered outside the <NotifizzProvider> tree. Move the provider higher up — typically wrapping your whole app at the root layout. If you only need state in one place, you can use <NotifizzInbox onStateChange={...}> directly without a provider.

State updates don't trigger re-renders.

useNotifizz returns React state internally — re-renders are automatic. If your component is memoised (e.g. React.memo) and re-rendering only on prop changes, ensure you destructure the values you need from useNotifizz() directly inside the component body, not via a stale closure.

Can I use `NotifizzProvider` and `NotifizzInbox` together?

Yes — that’s the common pattern. The provider exposes state to descendant components, the inbox renders the bell. Mount the inbox inside the provider tree once.

The widget mounts twice in dev mode (StrictMode).

'Invalid hook call' / 'Cannot read properties of null (reading useState)'.

This is almost always two copies of React loaded in your app, not a bug in the SDK. @notifizz/react declares react and react-dom as peer dependencies and uses yours — but a monorepo, a locally-linked package that ships its own React, a mismatched transitive version, or a misconfigured bundler can pull in a second one. React’s hook dispatcher then comes back null and any hook (including the SDK’s) crashes.First, confirm there’s really a duplicate — this should print a single version each:

npm ls react react-dom      # or: pnpm why react react-dom

Then force a single instance in your bundler:

// vite.config.ts
import { defineConfig } from 'vite';

export default defineConfig({
  resolve: { dedupe: ['react', 'react-dom'] },
});

// webpack.config.js
const path = require('path');

module.exports = {
  resolve: {
    alias: {
      react: path.resolve(__dirname, 'node_modules/react'),
      'react-dom': path.resolve(__dirname, 'node_modules/react-dom'),
    },
  },
};

// next.config.js — needed only when a linked/local package brings its own React
module.exports = { transpilePackages: ['@notifizz/react'] };

# .npmrc — hoist a single shared copy for peer dependencies
dedupe-peer-dependents=true

If a locally-linked dependency carries its own node_modules/react, deleting that nested copy also resolves it.

How do I switch user without unmounting the provider?

Pass new options.userId / options.token — the inbox effect is keyed on options.apiKey and options.authType, so changes to those re-authenticate. For a clean swap (no flash of the previous user’s inbox), conditionally render the provider so it unmounts/remounts when the user changes.

Server-rendering the page — what happens?

The widget is browser-only — NotifizzInbox and NotifizzProvider no-op when window is undefined. SSR your page normally; the widget hydrates and authenticates on the client. The rendered HTML contains the mount <div> but no widget content until the script loads.

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/react SDK Reference

`@notifizz/react` SDK reference

TL;DR

Installation

Components

`NotifizzInbox`

Props

`NotifizzInboxOptions`

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

`NotifizzProvider`

Hooks

`useNotifizz()`

Return value: `NotifizzBellContext`

Custom bell

Headless mode

State shape

Exported types

FAQ

See also

Notification Center overview

Authentication overview

Frontend quickstart

Backend quickstart

​@notifizz/react SDK reference

​TL;DR

​Installation

​Components

​NotifizzInbox

​Props

​NotifizzInboxOptions

​authType: "none" example (dev only)

​NotifizzProvider

​Hooks

​useNotifizz()

​Return value: NotifizzBellContext

​Custom bell

​Headless mode

​State shape

​Exported types

​FAQ

​See also

Notification Center overview

Authentication overview

Frontend quickstart

Backend quickstart

`@notifizz/react` SDK reference

TL;DR

Installation

Components

`NotifizzInbox`

Props

`NotifizzInboxOptions`

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

`NotifizzProvider`

Hooks

`useNotifizz()`

Return value: `NotifizzBellContext`

Custom bell

Headless mode

State shape

Exported types

FAQ

See also