Migrate to the New Inbox

Use Inbox with workflows from the current Dashboard or @novu/framework.

React: @novu/react
Angular, Vue, Vanilla JS, and headless clients: @novu/js

The legacy @novu/notification-center package, including its Angular, Vue, web component, iframe, and headless clients, is for legacy Dashboard workflows only.

Inbox replaces the legacy Notification Center. The notification object, action handlers, tabs, appearance, localization, and HMAC options are the same across hosts. The mount path differs by framework. Review the breaking changes, then use the React, Angular, Vue, or Vanilla JS section that matches your application.

Why you should upgrade

Appearance and layout options that replace the legacy styles API
A notification object that includes archive, snooze, severity, and action methods
A smaller client surface: @novu/react for React, @novu/js for every other host
Compatibility with current Dashboard workflows and @novu/framework

Breaking Changes

These changes apply to every host. React uses component props. Angular, Vue, and Vanilla JS pass the same fields to NovuUI options and mountComponent props.

Components

The PopoverNotificationCenter component has been replaced with the Inbox component.
The NotificationCenter component has been replaced with the Notifications component.
The NotificationBell component has been replaced with the Bell component.

Styling

The styles prop is replaced by an enhanced, easy to use appearance prop to customize the notification components. For more information on appearance customization, visit here.

Notification

Removal of seen, lastSeenDate, content, templateIdentifier, payload, cta properties from the Notification object.
Archive, snooze, and severity support were added to the Notification object.

Notification object

type Notification = {
- _id: string;
+ id: string;

- content: string;
+ body: string;

- cta: IMessageCTA;
+ redirect?: Redirect;
+ primaryAction?: Action;
+ secondaryAction?: Action;

- channel: ChannelTypeEnum;
+ channelType: ChannelType;

- payload: Record<string, unknown>;
+ data?: NotificationData;

- subscriber: Subscriber;
+ to: Subscriber;

- seen: boolean;
- lastSeenDate: string;
- templateIdentifier: string;

+ transactionId: string;
+ subject?: string;
+ isRead: boolean;
+ isSeen: boolean;
+ isArchived: boolean;
+ isSnoozed: boolean;
+ snoozedUntil?: string | null;
+ readAt?: string | null;
+ archivedAt?: string | null;
+ firstSeenAt?: string | null;
+ deliveredAt?: string[];
+ avatar?: string;
+ tags?: string[];
+ workflow?: Workflow;
+ severity: SeverityLevelEnum;

createdAt: string;
};

Types

type Workflow = {
  id: string;
  identifier: string;
  name: string;
  critical: boolean;
  tags?: string[];
  severity: SeverityLevelEnum;
};

type Subscriber = {
  id?: string;
  subscriberId: string;
  firstName?: string;
  lastName?: string;
  email?: string;
  phone?: string;
  avatar?: string;
  locale?: string;
  timezone?: string;
  data?: Record<string, unknown>;
};

type Redirect = {
  url: string;
  target?: '_self' | '_blank' | '_parent' | '_top' | '_unfencedTop';
};

type Action = {
  label: string;
  isCompleted: boolean;
  redirect?: Redirect;
};

The legacy _id is the notification identifier and is not the same value as transactionId, which identifies the workflow trigger.

Subscriber prop

The subscriberId prop is deprecated. Pass subscriber with either a subscriber ID string or a subscriber object.

- <Inbox applicationIdentifier="YOUR_APP_ID" subscriberId="YOUR_SUBSCRIBER_ID" />
+ <Inbox applicationIdentifier="YOUR_APP_ID" subscriber="YOUR_SUBSCRIBER_ID" />

Choose the Inbox package

Host	Uninstall	Install	Mount Inbox	Setup
React	`@novu/notification-center`	`@novu/react`	`<Inbox />`	React quickstart
Angular	Angular Notification Center wrapper	`@novu/js`	`NovuUI` from `@novu/js/ui`	Angular quickstart
Vue	Vue Notification Center wrapper	`@novu/js`	`NovuUI` from `@novu/js/ui`	Vue quickstart
Vanilla JS	Web component, iframe script, or `@novu/headless`	`@novu/js`	`NovuUI` from `@novu/js/ui`, or `@novu/js` for a custom headless client	Vanilla JS quickstart

There is no native Angular or Vue Inbox package. Those applications mount the same UI through @novu/js. React Native uses @novu/react-native. The breaking changes, tabs, appearance, actions, and notification methods on this page apply to every host. React uses component props. Angular, Vue, and Vanilla JS pass the same fields to NovuUI options and mountComponent props.

React

Uninstall @novu/notification-center and install @novu/react. Replace NovuProvider, PopoverNotificationCenter, and NotificationBell with <Inbox />. Use subscriber, not the deprecated subscriberId prop. The React examples below map the remaining components, fields, and handlers. For HMAC, localization, and layout, follow the React Inbox quickstart.

Angular

Uninstall the Angular Notification Center wrapper and install @novu/js. There is no native Angular Inbox package. Mount Inbox with NovuUI from @novu/js/ui on an existing header, navbar, or sidebar element. Use a template reference such as #novuInbox, mount in ngAfterViewInit, and unmount in ngOnDestroy. Pass appearance, tabs, localization, and click handlers in the constructor options or in mountComponent props. Follow the Angular Inbox quickstart for the install.

Vue

Uninstall the Vue Notification Center wrapper and install @novu/js. There is no native Vue Inbox package. Mount Inbox with NovuUI from @novu/js/ui from onMounted against a template ref, and unmount in onUnmounted. Inbox does not support server-side rendering. For Nuxt, wrap the component in <ClientOnly> and follow the Nuxt Inbox quickstart. Follow the Vue Inbox quickstart for the install.

Vanilla JS

Uninstall the web component, iframe embed, or @novu/headless client and install @novu/js. Mount Inbox with NovuUI from @novu/js/ui after DOMContentLoaded on an existing element. A bundler is required for the @novu/js/ui import. For a plain HTML page, follow the Vanilla JS Inbox quickstart, which loads the UI bundle and stylesheet. For a custom feed without the prebuilt UI, replace @novu/headless with @novu/js and rebuild queries, counts, and mutation methods against the current notification object. See the JavaScript SDK.

Basic usage

The examples below use @novu/react. For Angular, Vue, and Vanilla JS, pass the same options to NovuUI and the same handlers in mountComponent props.

Legacy implementation with `@novu/notification-center`

import {
  NovuProvider,
  PopoverNotificationCenter,
  NotificationBell,
} from '@novu/notification-center';

function Novu() {
  return (
    <NovuProvider subscriber="YOUR_SUBSCRIBER_ID" applicationIdentifier="YOUR_APP_ID">
      <PopoverNotificationCenter>
        {({ unseenCount }) => <NotificationBell unseenCount={unseenCount} />}
      </PopoverNotificationCenter>
    </NovuProvider>
  );
}
export default Novu;

Current implementation with `@novu/react`

import { Inbox } from '@novu/react';

function Novu() {
  return (
    <Inbox applicationIdentifier="YOUR_APPLICATION_IDENTIFIER" subscriber="YOUR_SUBSCRIBER_ID" />
  );
}

export default Novu;

Notification center without bell icon

The @novu/react package introduces a flexible way to display notifications as a list without the default bell icon. Use the Inbox and Notifications components to achieve this functionality.

Legacy implementation with `@novu/notification-center`

import { NovuProvider, NotificationCenter } from '@novu/notification-center';

function Novu() {
  return (
    <NovuProvider subscriber="YOUR_SUBSCRIBER_ID" applicationIdentifier="YOUR_APP_ID">
      <NotificationCenter colorScheme="dark" />
    </NovuProvider>
  );
}

export default Novu;

Current implementation with `@novu/react`

import { Inbox, Notifications } from '@novu/react';

function Novu() {
  return (
    <Inbox applicationIdentifier="YOUR_APP_ID" subscriber="YOUR_SUBSCRIBER_ID">
      <Notifications />
    </Inbox>
  );
}

export default Novu;

Custom bell icon

Customize the bell icon that triggers the notifications popover using the renderBell prop.

Legacy implementation with `@novu/notification-center`

import { NovuProvider, PopoverNotificationCenter } from '@novu/notification-center';
import CustomBell from './CustomBell'; // Your custom bell icon component

function Novu() {
  return (
    <NovuProvider subscriber="YOUR_SUBSCRIBER_ID" applicationIdentifier="YOUR_APP_ID">
      <PopoverNotificationCenter colorScheme="dark">
        {({ unseenCount }) => (
          <CustomBell
            unseenCount={unseenCount}
            colorScheme="dark"
            unseenBadgeBackgroundColor="#FFFFFF"
            unseenBadgeColor="#FF0000"
          />
        )}
      </PopoverNotificationCenter>
    </NovuProvider>
  );
}

export default Novu;

Current implementation with `@novu/react`

import { Inbox } from '@novu/react';
import CustomBell from './CustomBell'; // Your custom bell icon component

function Novu() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APP_ID"
      subscriber="YOUR_SUBSCRIBER_ID"
      renderBell={(unreadCount) => <CustomBell unreadCount={unreadCount} />}
    />
  );
}

export default Novu;

Notification actions

Handle user interactions with notifications effectively using the action handlers provided by @novu/react.

onNotificationClick

Trigger a callback function when a user clicks on a notification item.

Legacy implementation with `@novu/notification-center`

import {
  NovuProvider,
  PopoverNotificationCenter,
  NotificationBell,
  IMessage,
} from '@novu/notification-center';

function Novu() {
  function handleOnNotificationClick(message: IMessage) {
    // your logic to handle the notification click
    if (message?.cta?.data?.url) {
      window.location.href = message.cta.data.url;
    }
  }

  return (
    <NovuProvider subscriber="YOUR_SUBSCRIBER_ID" applicationIdentifier="YOUR_APP_ID">
      <PopoverNotificationCenter colorScheme="dark" onNotificationClick={handleOnNotificationClick}>
        {({ unseenCount }) => <NotificationBell unseenCount={unseenCount} />}
      </PopoverNotificationCenter>
    </NovuProvider>
  );
}

export default Novu;

Current implementation with `@novu/react`

import { Inbox } from '@novu/react';

function Novu() {
  const handleNotificationClick = (notification) => {
    // Your custom logic here
    console.log('Notification clicked:', notification);
  };

  return (
    <Inbox
      applicationIdentifier="YOUR_APP_ID"
      subscriber="YOUR_SUBSCRIBER_ID"
      onNotificationClick={handleNotificationClick}
    />
  );
}

export default Novu;

onPrimaryActionClick and onSecondaryActionClick

Handle primary and secondary actions within a notification explicitly.

Legacy implementation with `@novu/notification-center`

import {
  NovuProvider,
  PopoverNotificationCenter,
  IMessage,
  MessageActionStatusEnum,
  useUpdateAction,
  ButtonTypeEnum,
  NotificationBell,
} from '@novu/notification-center';

function Novu() {
  const CustomNotificationCenter = () => {
    const { updateAction } = useUpdateAction();

    const handleOnActionClick = async (
      templateIdentifier: string,
      btnType: ButtonTypeEnum,
      notification: IMessage
    ) => {
      if (templateIdentifier === 'friend-request') {
        if (btnType === 'primary') {
          /** Call your API to accept the friend request here **/

          /** And then update Novu that this action has been taken, so the user won't see the button again **/
          updateAction({
            messageId: notification._id,
            actionButtonType: btnType,
            status: MessageActionStatusEnum.DONE,
          });
        }
      }
    };

    return (
      <PopoverNotificationCenter colorScheme={'dark'} onActionClick={handleOnActionClick}>
        {({ unseenCount }) => <NotificationBell unseenCount={unseenCount} />}
      </PopoverNotificationCenter>
    );
  };

  return (
    <NovuProvider subscriber="YOUR_SUBSCRIBER_ID" applicationIdentifier="YOUR_APP_ID">
      <CustomNotificationCenter />
    </NovuProvider>
  );
}

export default Novu;

Current implementation with `@novu/react`

import { Inbox } from '@novu/react';

function Novu() {
  const handlePrimaryActionClick = (notification) => {
    // Handle primary action
    console.log('Primary action clicked:', notification);
  };

  const handleSecondaryActionClick = (notification) => {
    // Handle secondary action
    console.log('Secondary action clicked:', notification);
  };

  return (
    <Inbox
      applicationIdentifier="YOUR_APP_ID"
      subscriber="YOUR_SUBSCRIBER_ID"
      onPrimaryActionClick={handlePrimaryActionClick}
      onSecondaryActionClick={handleSecondaryActionClick}
    />
  );
}

export default Novu;

Avatar icons

In the legacy implementation, you could set a notification’s avatar icon by enabling the Add an avatar option in the workflow UI. Novu would then use the avatar field of the actor subscriber as the icon. In the new implementation, you can set the avatar icon for a notification by adding the avatar icon in the workflow UI. There are three options to choose from:

Use a default avatar icon.
Use a hard-coded avatar icon URL.
Use a payload variable to dynamically set the avatar icon.

For more information, refer to Icons. For advanced positioning and styling of the notifications popover, integrate third-party popover libraries such as Radix UI.

Legacy implementation with `@novu/notification-center`

import {
  PopoverNotificationCenter,
  NotificationBell,
  NovuProvider,
} from '@novu/notification-center';

function Novu() {
  return (
    <NovuProvider subscriber="YOUR_SUBSCRIBER_ID" applicationIdentifier="YOUR_APP_ID">
      <PopoverNotificationCenter position="left-start" offset={20}>
        {({ unseenCount }) => <NotificationBell unseenCount={unseenCount} />}
      </PopoverNotificationCenter>
    </NovuProvider>
  );
}

export default Novu;

Current implementation with `@novu/react` and Radix UI as an example

import React from 'react';
import * as RadixPopover from '@radix-ui/react-popover';
import { Inbox, Bell, Notifications } from '@novu/react';

function Novu() {
  return (
    <Inbox applicationIdentifier="YOUR_APP_ID" subscriber="YOUR_SUBSCRIBER_ID">
      <RadixPopover.Root>
        <RadixPopover.Trigger asChild>
          <Bell />
        </RadixPopover.Trigger>
        <RadixPopover.Portal>
          <RadixPopover.Content side="bottom" align="end" sideOffset={10}>
            <Notifications />
            <RadixPopover.Arrow />
          </RadixPopover.Content>
        </RadixPopover.Portal>
      </RadixPopover.Root>
    </Inbox>
  );
}

export default Novu;

Custom notification item

Customize the appearance and structure of individual notification items using the renderNotification prop.

Legacy implementation with `@novu/notification-center`

import {
  NovuProvider,
  PopoverNotificationCenter,
  NotificationBell,
} from '@novu/notification-center';

function Novu() {
  return (
    <NovuProvider subscriber="YOUR_SUBSCRIBER_ID" applicationIdentifier="YOUR_APP_ID">
      <PopoverNotificationCenter
        colorScheme={colorScheme}
        onNotificationClick={handlerOnNotificationClick}
        onActionClick={handlerOnActionClick}
        listItem={(notification, handleActionButtonClick, handleNotificationClick) => {
          return (
            <a
              href="/"
              onClick={(e) => {
                e.preventDefault();
                handleNotificationClick();
              }}>
              {notification.content}
            </a>
          );
        }}>
        {({ unseenCount }) => {
          return <NotificationBell unseenCount={unseenCount} />;
        }}
      </PopoverNotificationCenter>
    </NovuProvider>
  );
}

export default Novu;

Current implementation with `@novu/react`

import { Inbox } from '@novu/react';

function Novu() {
  const renderCustomNotificationItem = (notification) => (
    <div
      className={`notification-item ${notification.isRead ? 'read' : 'unread'}`}
      onClick={() => notification.read()}>
      <img src={notification.avatar} alt="Avatar" className="notification-avatar" />
      <div className="notification-content">
        <h4 className="notification-subject">{notification.subject}</h4>
        <p className="notification-body">{notification.body}</p>
      </div>
    </div>
  );

  return (
    <Inbox
      applicationIdentifier="YOUR_APP_ID"
      subscriber="YOUR_SUBSCRIBER_ID"
      renderNotification={renderCustomNotificationItem}
    />
  );
}

export default Novu;

Styling with appearance prop

Customize the overall look and feel of the notification components using the appearance prop, which supports both CSS objects and class names (including Tailwind CSS classes).

Legacy implementation with `@novu/notification-center`

import {
  NovuProvider,
  PopoverNotificationCenter,
  NotificationBell,
} from '@novu/notification-center';

function Novu() {
  return (
    <NovuProvider
      applicationIdentifier="YOUR_APP_ID"
      subscriber="YOUR_SUBSCRIBER_ID"
      styles={{ notifications: { listItem: { layout: { color: '#E3554D' } } } }}>
      <PopoverNotificationCenter>
        {({ unseenCount }) => <NotificationBell unseenCount={unseenCount} />}
      </PopoverNotificationCenter>
    </NovuProvider>
  );
}

export default Novu;

Current implementation with `@novu/react`

import { Inbox } from '@novu/react';

function Novu() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APP_ID"
      subscriber="YOUR_SUBSCRIBER_ID"
      appearance={{
        baseTheme: {
          variables: {
            colorBackground: '#1F2937',
            colorForeground: '#F9FAFB',
            colorPrimary: '#3B82F6',
            colorSecondaryForeground: '#9CA3AF',
            colorNeutral: '#374151',
          },
        },
        elements: {
          bellIcon: 'text-white',
          notificationItem: 'custom-class bg-gray-800 hover:bg-gray-700 p-4 rounded-md',
          notificationSubject: {
            color: '#E2E8F0',
            fontSize: '18px',
            fontWeight: 'bold',
          },
          notificationBody: {
            color: '#A0AEC0',
            fontSize: '14px',
          },
        },
      }}
    />
  );
}

export default Novu;

For more information on appearance customization visit here.

Multiple tabs support

Organize notifications into different categories using tabs by leveraging the tags property in workflow definitions and the tabs prop in the Inbox component.

Create multiple tabs

Legacy implementation with `@novu/notification-center`

After defining the feeds on the workflow UI, you were able to filter notifications based on the feedIdentifier.

import {
  NovuProvider,
  PopoverNotificationCenter,
  NotificationBell,
} from '@novu/notification-center';

function Novu() {
  return (
    <NovuProvider
      stores={[
        {
          storeId: 'product-updates',
          query: { feedIdentifier: 'product-updates' },
        },
        {
          storeId: 'user-activity',
          query: { feedIdentifier: 'user-activity' },
        },
      ]}
      subscriber="YOUR_SUBSCRIBER_ID"
      applicationIdentifier="YOUR_APP_ID">
      <PopoverNotificationCenter
        tabs={[
          { name: 'Product Updates', storeId: 'product-updates' },
          { name: 'User Activity', storeId: 'user-activity' },
        ]}
        colorScheme={colorScheme}
        onNotificationClick={handlerOnNotificationClick}
        onActionClick={handlerOnActionClick}>
        {({ unseenCount }) => {
          return <NotificationBell colorScheme={colorScheme} unseenCount={unseenCount} />;
        }}
      </PopoverNotificationCenter>
    </NovuProvider>
  );
}

export default Novu;

Current implementation with `@novu/react`

Define multiple workflows with relevant tags.

Add tags on the workflow Tags field. One tag can be used for multiple workflows.

Use those tags in the tabs prop of the Inbox component.

Each tab takes a filter object that supports tags, data, and severity. The older value array is deprecated, so replace value: ['security'] with filter: { tags: ['security'] }.

import { Inbox } from '@novu/react';

const tabs = [
  { label: 'All Notifications', filter: {} },
  { label: 'Security', filter: { tags: ['security'] } },
  { label: 'Promotions', filter: { tags: ['promotions'] } },
];

function InboxWithTabs() {
  return (
    <Inbox 
      applicationIdentifier="YOUR_APP_ID" subscriber="YOUR_SUBSCRIBER_ID" 
      tabs={tabs} 
    />
  );
}

export default InboxWithTabs;

Localization

Customize the language and text content of the notification components using the localization prop. Refer to the localization documentation.

HMAC encryption

The process remains the same as before. For more information, refer to Secure your inbox with HMAC encryption.

Handling notifications

Legacy mutation hooks such as useUpdateAction are replaced by methods on the notification object.

Method	Replaces	Description
`read()`	`useMarkNotificationAsRead`	Marks the notification as read.
`unread()`	`useMarkNotificationAsUnRead`	Marks the notification as unread.
`archive()`	No legacy equivalent	Archives the notification.
`unarchive()`	No legacy equivalent	Restores an archived notification.
`snooze(snoozeUntil)`	No legacy equivalent	Snoozes the notification until an ISO 8601 timestamp.
`unsnooze()`	No legacy equivalent	Cancels an active snooze.
`completePrimary()` and `completeSecondary()`	`useUpdateAction` with `MessageActionStatusEnum.DONE`	Marks an action button as completed.
`revertPrimary()` and `revertSecondary()`	`useUpdateAction` with `MessageActionStatusEnum.PENDING`	Returns an action button to its pending state.
`delete()`	No legacy equivalent	Deletes the notification.

Each method returns a promise, so handle failures rather than assuming the change succeeded.

import { Inbox } from '@novu/react';

function Novu() {
  const handleNotificationClick = (notification) => {
    notification.read();
  };

  const handlePrimaryActionClick = async (notification) => {
    // Call your own API first, then record the action in Novu.
    await acceptFriendRequest(notification.data?.requestId);
    await notification.completePrimary();
  };

  return (
    <Inbox
      applicationIdentifier="YOUR_APP_ID"
      subscriber="YOUR_SUBSCRIBER_ID"
      onNotificationClick={handleNotificationClick}
      onPrimaryActionClick={handlePrimaryActionClick}
    />
  );
}

export default Novu;

If you still have questions or need further assistance, please reach out to us at [email protected].

​Why you should upgrade

​Breaking Changes

​Components

​Styling

​Notification

​Subscriber prop

​Choose the Inbox package

​React

​Angular

​Vue

​Vanilla JS

​Basic usage

​Legacy implementation with @novu/notification-center

​Current implementation with @novu/react

​Notification center without bell icon

​Legacy implementation with @novu/notification-center

​Current implementation with @novu/react

​Custom bell icon

​Legacy implementation with @novu/notification-center

​Current implementation with @novu/react

​Notification actions

​onNotificationClick

​Legacy implementation with @novu/notification-center

​Current implementation with @novu/react

​onPrimaryActionClick and onSecondaryActionClick

​Legacy implementation with @novu/notification-center

​Current implementation with @novu/react

​Avatar icons

​Popover positioning

​Legacy implementation with @novu/notification-center

​Current implementation with @novu/react and Radix UI as an example

​Custom notification item

​Legacy implementation with @novu/notification-center

​Current implementation with @novu/react

​Styling with appearance prop

​Legacy implementation with @novu/notification-center

​Current implementation with @novu/react

​Multiple tabs support

​Create multiple tabs

​Legacy implementation with @novu/notification-center

​Current implementation with @novu/react

​Localization

​HMAC encryption

​Handling notifications

Why you should upgrade

Breaking Changes

Components

Styling

Notification

Subscriber prop

Choose the Inbox package

React

Angular

Vue

Vanilla JS

Basic usage

Legacy implementation with `@novu/notification-center`

Current implementation with `@novu/react`

Notification center without bell icon

Legacy implementation with `@novu/notification-center`

Current implementation with `@novu/react`

Custom bell icon

Legacy implementation with `@novu/notification-center`

Current implementation with `@novu/react`

Notification actions

onNotificationClick

Legacy implementation with `@novu/notification-center`

Current implementation with `@novu/react`

onPrimaryActionClick and onSecondaryActionClick

Legacy implementation with `@novu/notification-center`

Current implementation with `@novu/react`

Avatar icons

Popover positioning

Legacy implementation with `@novu/notification-center`

Current implementation with `@novu/react` and Radix UI as an example

Custom notification item

Legacy implementation with `@novu/notification-center`

Current implementation with `@novu/react`

Styling with appearance prop

Legacy implementation with `@novu/notification-center`

Current implementation with `@novu/react`

Multiple tabs support

Create multiple tabs

Legacy implementation with `@novu/notification-center`

Current implementation with `@novu/react`

Localization

HMAC encryption

Handling notifications