Skip to main content

​
React SDK

The @notifizz/react package provides React components and hooks to embed the Notifizz Notification Center in your React application.

​
Installation

npm install @notifizz/react

​
Components

​
NotifizzInbox

The main component. Renders the bell icon and notification center. 
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

PropTypeRequiredDefaultDescription
optionsNotifizzInboxOptionsYes—Authentication and display options.
renderBell(ctx: NotifizzBellContext) => ReactNodeNoDefault bellCustom bell render function.
onReady() => voidNo—Called when the widget is ready.
onStateChange(state: NotifizzState) => voidNo—Called on every state change.
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 widget mount point.

​
NotifizzInboxOptions

Combines authentication and display options:
OptionTypeRequiredDescription
apiKeystringYesYour Front API Key.
authType'firebase' | 'backendToken' | 'none'YesAuthentication strategy.
tokenstringConditionalAuth token (required for firebase and backendToken).
userIdstringConditionalRequired for backendToken and none.
userEmailstringConditionalRequired for backendToken and none.
positionNotifizzPositionNoBell position ('top-right', 'top-left', 'bottom-right', 'bottom-left').
notificationCenterStyles{ marginTop?: string }NoNotification center style overrides.
bellStyles{ marginRight?: string; marginLeft?: string }NoBell style overrides.

​
NotifizzProvider

Wraps your app (or a subtree) to provide notification state via React context. Use this when multiple components need access to notification state. 
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>
  );
}

​
Props

PropTypeRequiredDescription
optionsNotifizzInboxOptionsYesAuthentication and display options.
serverUrlstringNoWidget server URL.
apiUrlstringNoAPI base URL.
widgetPathstringNoWidget script path.
mountIdstringNoDOM element ID for the widget mount point.
childrenReactNodeYesChild components.

​
Hooks

​
useNotifizz

Access notification state and controls from any component inside a NotifizzProvider. 
import { useNotifizz } from "@notifizz/react";

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

  if (!isReady) return null;

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

​
Return value: NotifizzBellContext

PropertyTypeDescription
unreadCountnumberCurrent unread notification count.
isOpenbooleanWhether the notification center is open.
isReadybooleanWhether the widget has loaded.
toggle() => voidToggle the notification center.
open() => voidOpen the notification center.
close() => voidClose the notification center.
useNotifizz must be called from a component inside a NotifizzProvider. Calling it outside will throw an error.

​
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 provides the same NotifizzBellContext as the useNotifizz hook.

​
Headless mode

Headless mode gives you full control over the notification UI while Notifizz handles the real-time data and state. This is ideal when you want notifications to match your app’s design system exactly.
Use NotifizzProvider + useNotifizz without rendering NotifizzInbox to build a fully custom notification UI: 
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>
  );
}

​
Exported types

The following types can be imported from @notifizz/react:
TypeDescription
NotifizzStateWidget state object (isReady, isOpen, unreadCount, lastUpdated, hasError?, errorCode?).
NotifizzBellContextBell context with state + controls (unreadCount, isOpen, isReady, toggle, open, close).
NotifizzInboxPropsProps accepted by NotifizzInbox.
NotifizzInboxOptionsCombined authentication and display options.
NotifizzConfigInternal configuration (apiKey, apiUrl, serverUrl, widgetPath).
AuthOptionsAuthentication fields (apiKey, authType, token?, userId?, userEmail?).

​
Next steps

Frontend quickstart

Get started with a complete example in under 5 minutes.

Shared concepts

Positioning, styling, state model, and widget lifecycle.