API Reference
React Notification Center API Reference
This page contains complete documentation about the React Notification Center package. You can find here the list of all the components, hooks, and props that you can use.
Components
Components are the building blocks of the React Notification Center package. They are used to build the UI of the notification center.
NovuProvider
The NovuProvider is the root component of the React Notification Center package. It is used to wrap the components code and provide the notifications feed context to all its children. It’s responsible for establishing the notification center session, managing the web socket connection, and fetching the notifications feed.
Prop | Type | Description |
---|---|---|
backendUrl | string (optional) | The custom backend URL, your own deployed instance of the API. The default is https://api.novu.co.app/. |
socketUrl | string (optional) | The custom socket URL, your own deployed instance of the WS app. The default is https://ws.novu.co/. |
applicationIdentifier | string | The app id is taken from the Novu Settings -> API Keys tab. |
subscriberId | string | The unique user id from your system. |
subscriberHash | string (optional) | The HMAC encrypted subscriberId. Read about hmac encryption |
stores | IStore (optional) | The connection object between feed and notification center tab. |
i18n | ITranslationEntry | ITranslationContent (optional) | The prop allows to configure the UI language. |
styles | NotificationCenterStyles (optional) | The prop allowing to style the notification center. It’s based on the CSSInterpolation object from the @emotion/css package. |
initialFetchingStrategy | IFetchingStrategy (optional) | The fetching strategy. By default notifications feed and user preferences are not fetched until the notification center is opened. You might need to tweak this configuration when building a custom UI and if you need to fetch notifications right away. Also it’s possible to change it when some action happens using the useNovuContext hook and setFetchingStrategy prop. |
children | object | The ReactNode object type, the “consumer” of the NovuProvider context. |
onLoad | function (optional) | The function that is called with an organization object after the notification center session is initialized. |
Props interface
Store interface
I18NLanguage interface
Styles interface
Fetching strategy interface
PopoverNotificationCenter
The floating popover component that appears when clicking on the NotificationBell button. It renders the NotificationCenter component inside its content.
Prop | Type | Description |
---|---|---|
position | string (optional) | Position of the popover relative to the bell icon. It is based on the Mantine Popover. The default is set to bottom-end . |
offset | number (optional) | Gap between the Bell icon and Popover in px. |
colorScheme | string | The UI light or dark mode. |
theme | INovuTheme (optional) | The theme object allowing you to override light and dark colors of the UI components. Deprecated for styling, please use the styles prop on the NovuProvider. |
tabs | ITab(optional) | Allows to define separate UI tabs for the notifications feed. The array of connection objects between the feed tab and stores (that you define on the NovuProvider) and feed identifier. |
listItem | ListItem (optional) | The render function allowing you to define the custom element for the notification list item. |
showUserPreferences | boolean (optional) | The flag that enables to show/hide the user preferences. By default it is enabled. |
allowedNotificationActions | boolean (optional) | The flag that enables to show/hide the dots menu for actions performed on a notification. By default it is enabled. |
onUrlChange | function (optional) | The function that is called when the notification item has a CTA of type redirect and is clicked. |
onNotificationClick | function (optional) | The function that is called when the notification item is clicked. |
onUnseenCountChanged | function (optional) | The function that is called when the unseen notifications count changed. |
children | function | The render function that allows you to define the custom bell button. It’s called with an argument that has unseenCount prop the number of unseen notifications. |
header | function (optional) | The render function that allows you to define the custom header component. |
footer | function (optional) | The render function that allows you to define the custom footer component. |
emptyState | JSX.Element (optional) | The render function that allows you to define the custom component for the empty notifications list state. |
onActionClick | function (optional) | The callback function triggered when the notification button is clicked. |
actionsResultBlock | function (optional) | The render function that allows you to define the custom component that will be rendered after the notification button is clicked. |
onTabClick | function (optional) | The callback function triggered when the notifications feed tab changes. |
preferenceFilter | function (optional) | The callback function triggered when filtering the subscriber preference. |
Props interface
More information about the IMessage interface, and the theme interface.
The tab interface
The list item interface
NotificationCenter
The component that renders the notifications feed and allows to update the user preferences.
Prop | Type | Description |
---|---|---|
colorScheme | string | The UI light or dark mode. |
theme | INovuTheme (optional) | The theme object allowing you to override light and dark colors of the UI components. Deprecated for styling, please use the styles prop on the NovuProvider. |
tabs | ITab(optional) | Allows to define separate UI tabs for the notifications feed. The array of connection objects between the feed tab and stores (that you define on the NovuProvider) and feed identifier. |
listItem | ListItem (optional) | The render function allowing you to define the custom element for the notification list item. |
showUserPreferences | boolean (optional) | The flag that enables to show/hide the user preferences. By default it is enabled. |
allowedNotificationActions | boolean (optional) | The flag that enables to show/hide the dots menu for actions performed on a notification. By default it is enabled. |
onUrlChange | function (optional) | The function that is called when the notification item has a CTA of type redirect and is clicked. |
onNotificationClick | function (optional) | The function that is called when the notification item is clicked. |
onUnseenCountChanged | function (optional) | The function that is called when the unseen notifications count changed. |
header | function (optional) | The render function that allows you to define the custom header component. |
footer | function (optional) | The render function that allows you to define the custom footer component. |
emptyState | JSX.Element (optional) | The render function that allows you to define the custom component for the empty notifications list state. |
onActionClick | function (optional) | The callback function triggered when the notification button is clicked. |
actionsResultBlock | function (optional) | The render function that allows you to define the custom component that will be rendered after the notification button is clicked. |
onTabClick | function (optional) | The callback function triggered when the notifications feed tab changes. |
preferenceFilter | function (optional) | The callback function triggered when filtering the subscriber preference. |
Props interface
NotificationBell
The component that renders the notification bell with the unseen notifications count.
Prop | Type | Description |
---|---|---|
unseenCount | number (optional) | The number of unseen notifications. |
unseenBadgeColor | string or object (optional) | The unseen notifications count badge color. |
unseenBadgeBackgroundColor | string (optional) | The background color of the notification unseen count badge. |
colorScheme | string (optional) | The UI light or dark mode. |
Props interface
Hooks
useNotifications
This hook that allows you to get the notifications feed data and unseen notifications count. The notifications are fetched only when the fetchingStrategy.fetchNotifications
is set to true interface, check the initialFetchingStrategy
prop on the NovuProvider component.
useNotifications
hook return interface
Description of the useNotifications
hook return interface properties
Prop | Type | Description |
---|---|---|
storeId | string | active storeId |
stores | IStore[] | array of IStore passed to the NovuProvider. |
unseenCount | number | unseen notifications (messages) count. |
notifications | IMessage[] | The feed notifications array. |
hasNextPage | boolean | flag indicating if the next notifications page to fetch is available. |
isLoading | boolean | flag indicating if the initial notifications fetch request is on the fly. |
isFetching | boolean | flag indicating if the notifications are fetching including initial fetch. |
isFetchingNextPage | boolean | flag indicating if the next notifications page request in on the fly. |
setStore | function | function used to change the current notifications IStore |
fetchNextPage | function | function that fires the fetch request for the next notifications page. |
refetch | function | function used to refetch all the notifications, when multiple page requests were made it will refetch all of them. |
markNotificationAsRead | function | function takes the notification (message) messageId as an argument and marks that notification (message) as read. |
markNotificationAsUnRead | function | function takes the notification (message) messageId as an argument and marks that notification (message) as unread. |
markNotificationAsSeen | function | function takes the notification (message) messageId as an argument and marks that notification (message) as seen. |
markFetchedNotificationsAsRead | function | function marks all the fetched notifications as read. |
markFetchedNotificationsAsSeen | function | function allowing you to mark all the fetched notifications as seen. |
markAllNotificationsAsRead | function | function allowing you to mark all notifications as read. |
markAllNotificationsAsSeen | function | function allowing you to mark notifications as seen. |
removeMessage | function | function takes the notification (message) messageId as an argument and delete a notification. |
removeAllMessages | function | The function allowing you to delete all notifications or a specific feed’s (store’s) notifications at once. |
useFetchNotifications
useFetchNotifications
can fetche the notifications for a particular feed. It’s a thin version of the useNotifications
hook and is based on the useInfiniteQuery
hook from the react-query
library. Notifications can be filtered using payload
property. Check all properties of IStoreQuery interface. The notifications are fetched only when the fetchingStrategy.fetchNotifications
is set to true interface, check the initialFetchingStrategy
prop on the NovuProvider component.
useFetchNotifications
hook return args
useFetchNotifications
hook return interface
useUnseenCount
useUnseenCount
returns the total unseen notifications count. Under the hood it uses the socket connection to get the unseen count updates.
useUnseenCount
hook args interface
useUnseenCount
hook return interface
useSocket
useSocket
hooks is used to get the reference to socket object.
useSocket
return interface
useSocket
supported events
Event | Description |
---|---|
notification_received | Triggered when a new notification is received |
unseen_count_changed | Triggered when the count of unseen notifications changes |
unread_count_changed | Triggered when the count of unread notifications changes |
useNovuContext
useNovuContext
hook is used to get the reference to the NovuProvider context.
useNovuContext
hook return interface
useFeedUnseenCount
useFeedUnseenCount
hook fetches the unseen count for a particular feed.
useFeedUnseenCount
hook args interface
useFeedUnseenCount
hook return interface
useFetchOrganization
useFetchOrganization
hok fetches the current organization information.
useFetchOrganization
hook args interface
useFetchOrganization
hook return interface
useFetchUserPreferences
useFetchUserPreferences
hook fetches the user preferences.
useFetchUserPreferences
hook args interface
useFetchUserPreferences
hook return interface
useUpdateUserPreferences
useUpdateUserPreferences
hook is used to update the user preferences.
useUpdateUserPreferences
hook args interface
useUpdateUserPreferences
hook return interface
useUpdateAction
useUpdateAction
hook can be used to update the notification action button status.
useUpdateAction
hook args interface
useUpdateAction
hook return interface
useMarkNotificationsAs
useMarkNotificationsAs
hook that marks the notifications as read or seen.
useMarkNotificationsAs
hook args interface
useMarkNotificationsAs
hook return interface
useRemoveNotification
useRemoveNotification
hook allows you to remove a message. It will delete the message for the subscriber and will refetch the feed.
useRemoveNotification
hook args interface
useRemoveNotification
hook return interface
useRemoveNotifications
useRemoveNotifications
hook allows you to remove multiple messages with a limit of 100 messageIds in single call.
useRemoveNotifications
hook args interface
useRemoveNotifications
hook return interface
useRemoveAllNotifications
useRemoveAllNotifications
hook allows you to remove all messages of all feeds. feedId can be used as param to delete only specific feed’s messages.
useRemoveAllNotifications
hook args interface
useRemoveAllNotifications
hook return interface
useTranslations
useTranslations
hook allows you to get the reference to the translations object.
useTranslations
returns interface
useNovuTheme
useNovuTheme
hook can be used to get the reference to the theme object.
useNovuTheme
hook return interface
The theme interface
IThemeLayout
Property | Default Value (Light Theme) | Default Value - (Dark Theme) |
---|---|---|
background | #FFFFFF | #1E1E26 |
boxShadow | 0px 5px 15px rgba(122, 133, 153, 0.25) | 0px 5px 20px rgba(0, 0, 0, 0.2) |
wrapper.secondaryFontColor | #BEBECC | #525266 |
IThemeHeader
Property | Default Value (Light Theme) | Default Value - (Dark Theme) |
---|---|---|
badgeColor | linear-gradient(0deg,#FF512F 0%,#DD2476 100%) | linear-gradient(0deg,#FF512F 0%,#DD2476 100%) |
badgeTextColor | #FFFFFF | #FFFFFF |
fontColor | #828299 | #FFFFFF |
IThemePopover
Property | Default Value (Light Theme) | Default Value - (Dark Theme) |
---|---|---|
arrowColor | #FFFFFF | #1E1E26 |
IThemeNotificationListItem
Property | Default Value (Light Theme) | Default Value - (Dark Theme) |
---|---|---|
seen.fontColor | #828299 | #FFFFFF |
seen.background | #F5F8FA | #23232B |
seen.timeMarkFontColor | #BEBECC | #525266 |
unseen.fontColor | #828299 | #FFFFFF |
unseen.background | #FFFFFF | #292933 |
unseen.boxShadow | 0px 5px 15px rgba(122, 133, 153, 0.25) | 0px 5px 20px rgba(0, 0, 0, 0.2) |
unseen.notificationItemBeforeBrandColor | linear-gradient(0deg,#FF512F 0%,#DD2476 100%) | linear-gradient(0deg,#FF512F 0%,#DD2476 100%) |
unseen.timeMarkFontColor | #828299 | #828299 |
buttons.primary.backGroundColor | linear-gradient(99deg,#DD2476 0% 0%, #FF512F 100% 100%) | linear-gradient(99deg,#DD2476 0% 0%, #FF512F 100% 100%) |
buttons.primary.fontColor | #FFFFFF | #FFFFFF |
buttons.primary.removeCircleColor | white | white |
buttons.primary.fontFamily | inherit | inherit |
buttons.secondary.backGroundColor | #F5F8FA | #3D3D4D |
buttons.secondary.fontColor | #525266 | #FFFFFF |
buttons.secondary.removeCircleColor | #525266 | #525266 |
buttons.secondary.fontFamily | inherit | inherit |
IThemeActionsMenu
Property | Default Value (Light Theme) | Default Value - (Dark Theme) |
---|---|---|
dotsButtonColor | #A1A1B2 | #525266 |
dropdownColor | #FFFFFF | #292933 |
hoverColor | #F5F8FA | #3D3D4D |
fontColor | #525266 | #FFFFFF |
IThemeUserPreferences
Property | Default Value (Light Theme) | Default Value - (Dark Theme) |
---|---|---|
settingsButtonColor | #A1A1B2 | #525266 |
accordion.background | #FFFFFF | #292933 |
accordion.fontColor | #525266 | #FFFFFF |
accordion.secondaryFontColor | #828299 | #828299 |
accordion.boxShadow | 0px 5px 15px rgba(122, 133, 153, 0.25) | 0px 5px 20px rgba(0, 0, 0, 0.2) |
accordion.arrowColor | #828299 | #828299 |
accordion.arrowColor | #EDF0F2 | #3D3D4D |
accordionItem.fontColor.active | #525266 | #FFFFFF |
accordionItem.fontColor.inactive | #BEBECC | #828299 |
accordionItem.icon.active | #525266 | #FFFFFF |
accordionItem.icon.inactive | #BEBECC | #525266 |
accordionItem.switch.backgroundChecked | linear-gradient(0deg,#FF512F 0%,#DD2476 100%) | linear-gradient(0deg,#FF512F 0%,#DD2476 100%) |
accordionItem.switch.backgroundUnchecked | #BEBECC | #3D3D4D |
footer.logoTextColor | #000000 | #FFFFFF |
footer.logoPrefixFontColor | #A1A1B2 | #525266 |
loaderColor | linear-gradient(0deg,#FF512F 0%,#DD2476 100%) | linear-gradient(0deg,#FF512F 0%,#DD2476 100%) |
IThemeFooter
Property | Default Value (Light Theme) | Default Value - (Dark Theme) |
---|---|---|
logoTextColor | #000000 | #FFFFFF |
logoPrefixFontColor | #A1A1B2 | #525266 |
customization properties
Property | type | Default Value (Light Theme) | Default Value - (Dark Theme) |
---|---|---|---|
colorScheme | string | light | light |
unseenBadgeColor | string or ISvgStopColor | - | - |
unseenBadgeBackgroundColor | string | #FFFFFF | #1E1E26 |
ISvgStopColor
Property | Default Value (Light Theme) | Default Value - (Dark Theme) |
---|---|---|
stopColor | #FF512F | #FF512F |
stopColorOffset | #DD2476 | #DD2476 |
Others
The notification IMessage
model
IMessage
model has the following properties:
Property | Type | Description |
---|---|---|
_id | string | A unique Novu message identifier |
channel | ChannelTypeEnum | Use to specify the actual channel of this message (in_app will be used here) |
seen | boolean | Whether the notification item was read by the user, changed when the user clicks on the notification |
lastSeenDate | ISODate | When the user has last seen the notification |
content | string | An HTML string of the generated notification content with parsed and replaced variables |
templateIdentifier | string | A unique Novu workflow identifier |
payload | Record<string, unknown> | The payload object that was passed to the trigger even of the workflow. |
createdAt | ISODate | The creation date of the message |
cta.type | ChannelCTATypeEnum | The type of the CTA specified in the admin panel |
cta.data.url | string | The redirect URL set in the admin panel, can be used to navigate on notification click |
cta.action.status | boolean | Indication whether the action occurred |
cta.action.buttons | IMessageButton[] | Array of action buttons |
cta.action.result.payload | Record<string, unknown> | Payload object that send on updateAction method in useNotifications hook |
cta.action.result.type | ButtonTypeEnum | Type of the button |
subscriber | SubscriberProps | Subscriber object that contains information about the subscriber |
SubscriberProps
Property | Type | Description |
---|---|---|
_id | string | Auto-generated identifier for the subscriber entity in the database |
firstName | string | First name of the subscriber |
subscriberId | string | identifier of the subscriber entity in the Novu Web Dashboard |
IMessageButton
Property | Type | Description |
---|---|---|
type | ButtonTypeEnum | Button type enum |
content | string | Button inner text |
ChannelCTATypeEnum
Property | Value |
---|---|
REDIRECT | redirect |
ChannelTypeEnum
Property | Value |
---|---|
IN_APP | in_app |
SMS | sms |
CHAT | chat |
PUSH | push |
ButtonTypeEnum
Property | Value |
---|---|
PRIMARY | primary |
SECONDARY | secondary |
Was this page helpful?