The useNotifications hook is a convenient way to fetch the list of notifications. By default, it fetches both unread and read notifications, but you can apply filters to retrieve only the relevant notifications for your specific use case.

The notifications fetched are paginated, and the hook provides a fetchMore function to load more notifications. The fetched notifications are stored in the notifications array and are appended to the existing notifications as more are loaded.

Any action performed on a notification instance, like marking it as read, will optimistically update the notification, triggering a re-render in the hook and updating the notifications list accordingly, so you don’t need to refetch and manually update your UI.

​
useNotifications props

tags
string[]

Workflow tags can be used to filter notifications, and organize them into different groups. Read more about how can you define workflow tags.

read
boolean

Filter notifications based on their read status. If not provided, all read/unread notifications will be returned.

archived
boolean

Filter notifications based on their archived status. Archived notifications are also read at the same time. If not provided, all archived/unarchived notifications will be returned.

limit
number

Limit the number of notifications to be fetched. It can take any number between 1 and 100. Default is 10.

onSuccess
Function

Callback function that will be called when the notifications are successfully fetched. In the callback argument, you will receive the fetched notifications.

onError
Function

Callback function that will be called when there is an error fetching the notifications. In the callback argument, you will receive the error object.

​
useNotifications returns

notifications
Notification[] | undefined

An array of notifications fetched by the hook. If there are no notifications fetched yet, it will be undefined.

isLoading
boolean

A boolean value indicating the first fetch for notifications is in-flight.

isFetching
boolean

A boolean value indicating whether the hook is fetching more notifications.

error
NovuError | undefined

An error object that will be populated if there is an error fetching the notifications.

hasMore
boolean

A boolean value indicating whether there are more notifications available to fetch.

fetchMore
Function

A function that can be called to fetch more notifications. It will fetch the next page of notifications and append them to the existing notifications.

refetch
Function

A function that can be called to refetch the notifications. It will clear the existing notifications and fetch the first page of notifications.

readAll
Function

A function that can be called to mark all notifications as read, including those that have not been fetched.

archiveAll
Function

A function that can be called to archive all notifications, including those that have not been fetched.

archiveAllRead
Function

A function that can be called to archive all read notifications, including those that have not been fetched.

​
Example usage

import { useNotifications } from '@novu/react/hooks';

const NotificationsList = () => {
  const { notifications, isLoading, fetchMore, hasMore } = useNotifications();

  return (
    <Show when={!isLoading} fallback={<NotificationListSkeleton />}>
      <Show
        when={notifications && notifications.length > 0}
        fallback={<EmptyNotificationList />}
      >
        <InfiniteScroll
          dataLength={notifications?.length ?? 0}
          fetchMore={fetchMore}
          hasMore={hasMore}
          loader={<LoadMoreSkeleton />}
        >
          {notifications?.map((notification) => {
            return (
              <NotificationItem
                key={notification.id}
                notification={notification}
              />
            );
          })}
        </InfiniteScroll>
      </Show>
    </Show>
  );
};

Was this page helpful?

NovuProviderusePreferences