Comments - Notifications

Notifications are a key part of a commenting experience, learn how to add them to your product in different ways: by adding a notifications inbox to your app, by differentiating unread comments in threads, and by also notifying users via email.

Notifications inbox

Add a notifications inbox to your app to keep users informed about the threads they are participating in with unread comments, mentions, and more.

An inbox as shown above can be built (and customized) using a combination of hooks and components.

LiveblocksContext

Comments—as many other Liveblocks features—takes place inside rooms. Notifications on the other hand, are global and accessible without entering rooms. This means that Notifications isn’t available on createRoomContext and within RoomProvider, but instead on createLiveblocksContext and within LiveblocksProvider.

import { createClient } from "@liveblocks/client";import { createRoomContext, createLiveblocksContext } from "@liveblocks/react";
const client = createClient({  authEndpoint: "/api/liveblocks-auth",});
export const { RoomProvider, useThreads } = createRoomContext(client);
export const { LiveblocksProvider, useInboxNotifications } =  createLiveblocksContext(client);

Unlike RoomProvider, LiveblocksProvider doesn’t call Liveblocks servers when mounted, so it can (and should) live higher in the component tree of your app. Features outside of rooms like Notifications can now be used anywhere in your app, without entering rooms.

import { LiveList, LiveMap, LiveObject } from "@liveblocks/client";import { LiveblocksProvider } from "./liveblocks.config";
function AppRoot() {  return <LiveblocksProvider>{/* children */}</LiveblocksProvider>;}

useInboxNotifications

To get a list of a user’s notifications, we can use useInboxNotifications.

import { useInboxNotifications } from "./liveblocks.config";
const { inboxNotifications } = useInboxNotifications();

Inbox notifications are different from “normal” notifications in the sense that they can group multiple activities together and evolve over time, which makes more sense when building a notifications inbox. In the case of Comments, inbox notifications are grouped per thread, which means that if there are 4 new comments in a thread you’re participating in, you will have a single inbox notification for it, instead of 4 “normal” notifications.

By default, you receive inbox notifications for threads you are participating in: if you create it, comment in it, or if someone mentions you in it. For example, in the image below, Quinn Elton and Emil Joyce are both participants.

This behavior can be customized per room, learn more about it in the Notifications settings section.

Components

To display inbox notifications, @liveblocks/react-comments comes with two default components: InboxNotification and InboxNotificationList.

import {  InboxNotification,  InboxNotificationList,} from "@liveblocks/react-comments";import { useInboxNotifications } from "./liveblocks.config";
function Inbox() {  const { inboxNotifications } = useInboxNotifications();
  return (    <InboxNotificationList>      {inboxNotifications.map((inboxNotification) => (        <InboxNotification          key={inboxNotification.id}          inboxNotification={inboxNotification}        />      ))}    </InboxNotificationList>  );}

You can then decide to display this list of notifications in a popover, a dedicated page, etc.

Missing pieces

We now have a list of notifications, but we’re missing a few things:

• Display the number of unread notifications (or just a dot) outside of the inbox
• Allow users to mark all notifications as read at once

To display the number of unread notifications, you can use useUnreadInboxNotificationsCount.

const { count } = useUnreadInboxNotificationsCount();
<span className="notifications-inbox-badge">{count}</span>;

To mark all notifications as read, you can use useMarkAllInboxNotificationsAsRead.

const markAllInboxNotificationsAsRead = useMarkAllInboxNotificationsAsRead();
<button onClick={markAllInboxNotificationsAsRead}>Mark all as read</button>;

That’s it! You now have a fully functional notifications inbox in your app.

Unread indicators

Threads leverage Notifications behind-the-scenes to keep track of unread comments so viewing a thread will also mark its inbox notification as read, and vice versa.

If you use the default Thread component, it will automatically handle marking threads as read when they are viewed and show unread indicators when there are unread comments in threads you are participating in.

If you’re building your own custom Thread component, you can use useMarkThreadAsRead and useThreadSubscription to replicate (or customize) this behavior.

Notifications settings

As we’ve seen earlier, by default you receive inbox notifications for threads you are participating in. This setting can be customized for each user and per room:

• "all" to be notified about everything
• "replies_and_mentions" for the default setting
• "none" to mute the room

You can use useRoomNotificationSettings to build a settings picker in your app and allow users to change their own notification settings for the current room, or use updateRoomNotificationSettings server-side to control them yourself: for example, to automatically make a document’s author notified about everything in their document.

Permissions

Access token

When using access token authentication, Liveblocks disregards the permissions specified in the tokens and returns all notifications created for the user. Consequently, a user will receive notifications for mentions in comments within rooms they do not have access to.

For greater control over notification permissions, we recommend utilizing ID tokens.

ID token

When using ID token authentication, Liveblocks reads the permissions set on the room, and uses these to deliver notifications that the user is authorized to view.

Email notifications

Using webhooks, it’s also possible to send updates about a user’s inbox notifications via email. Learn more about it in the dedicated page.