useNotifications

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>
  );
};