Headless Mode | Novu Documentation

Build a fully custom notification inbox with the headless version of Novu's inbox notification package without being constrained by the default Inbox UI or dependencies.

This lightweight solution gives you full control over the UI and provides all the necessary API methods for fetching, managing, and receiving real-time notifications in your application.

Getting started

Follow these steps to initialize the SDK and fetch notifications:

Install the SDK package

npm i @novu/js

Initialize the SDK

Initialize the Novu client with your application identifier and the current user's subscriber ID.

import { Novu } from "@novu/js";
 
export const novu = new Novu({
  applicationIdentifier: 'YOUR_APPLICATION_IDENTIFIER',
  subscriber: 'YOUR_SUBSCRIBER_ID',
});

Fetch notifications

Use the novu.notifications.list() method to retrieve a paginated list of notifications for the subscriber.

const response = await novu.notifications.list({
  limit: 30,
});
 
const notifications = response.data.notifications;

Display notifications

Use your preferred framework or templating logic to render the notifications. For example, you can loop through the notifications array and display relevant fields:

notifications.forEach(notification => {
 console.log(`Notification ID: ${notification.id}`);
 console.log(`Title: ${notification.subject}`);
 console.log(`Content: ${notification.body}`);
});

Real-time notifications

Events are emitted when notifications are received, and when the unread notificatons count changes. novu.on() is used to listen to these events.

novu.on("notifications.notification_received", (data) => {
  console.log("new notification =>", data);
});
 
novu.on("notifications.unread_count_changed", (data) => {
  console.log("new unread notifications count =>", data);
});

For the full list of methods available, see the API Reference.

Available methods

Here are a few commonly used notification, preferences and events methods you’ll likely need when working headlessly:

Action	Method Example
Fetch notifications	`novu.notifications.list()`
Count notifications	`novu.notifications.count()`
Mark as read	`notification.read()` or `novu.notifications.read({ notificationId })`
Mark all as seen	`novu.notifications.seenAll()`
Archive notification	`notification.archive()`
Fetch subscriber's preferences	`novu.preferences.list();`
Real-time events	`novu.on('notifications.notification_received', handler)`

You can interact with individual notification instances or perform bulk actions through the notifications namespace.

See the full list of supported methods and events in the JavaScript SDK documentation.

Headless notification Inbox for JavaScript applications