Comments

BlockNote supports Comments, Comment Threads (replies) and emoji reactions out of the box.

To enable comments in your editor, you need to:

• provide a resolveUsers so BlockNote can retrieve and display user information (names and avatars).
• provide a ThreadStore so BlockNote can store and retrieve comment threads.
• enable real-time collaboration (see Real-time collaboration)

const editor = useCreateBlockNote({
  resolveUsers: async (userIds: string[]) => {
    // return user information for the given userIds (see below)
  },
  comments: {
    threadStore: yourThreadStore, // see below
  },
  // ...
  collaboration: {
    // ... // see real-time collaboration docs
  },
});

Demo

ThreadStores

A ThreadStore is used to store and retrieve comment threads. BlockNote is backend agnostic, so you can use any database or backend to store the threads. BlockNote comes with several built-in ThreadStore implementations:

YjsThreadStore

The YjsThreadStore provides direct Yjs-based storage for comments, storing thread data directly in the Yjs document. This implementation is ideal for simple collaborative setups where all users have write access to the document.

import { YjsThreadStore } from "@blocknote/core/comments";
 
const threadStore = new YjsThreadStore(
  userId, // The active user's ID
  yDoc.getMap("threads"), // Y.Map to store threads
  new DefaultThreadStoreAuth(userId, "editor"), // Authorization information, see below
);

Note: While this is the easiest to implement, it requires users to have write access to the Yjs document to leave comments. Also, without proper server-side validation, any user could technically modify other users' comments.

RESTYjsThreadStore

The RESTYjsThreadStore combines Yjs storage with a REST API backend, providing secure comment management while maintaining real-time collaboration. This implementation is ideal when you have strong authentication requirements, but is a little more work to set up.

In this implementation, data is written to the Yjs document via a REST API which can handle access control. Data is still retrieved from the Yjs document directly (after it's been updated by the REST API), this way all comment information automatically syncs between clients using the existing collaboration provider.

import {
  RESTYjsThreadStore,
  DefaultThreadStoreAuth,
} from "@blocknote/core/comments";
 
const threadStore = new RESTYjsThreadStore(
  "https://api.example.com/comments", // Base URL for the REST API
  {
    Authorization: "Bearer your-token", // Optional headers to add to requests
  },
  yDoc.getMap("threads"), // Y.Map to retrieve commend data from
  new DefaultThreadStoreAuth(userId, "editor"), // Authorization rules (see below)
);

An example implementation of the REST API can be found in the example repository (opens in a new tab).

Note: Because writes are executed via a REST API, the RESTYjsThreadStore is not suitable for local-first applications that should be able to add and edit comments offline.

TiptapThreadStore

The TiptapThreadStore integrates with Tiptap's collaboration provider for comment management. This implementation is designed specifically for use with Tiptap's collaborative editing features.

import {
  TiptapThreadStore,
  DefaultThreadStoreAuth,
} from "@blocknote/core/comments";
import { TiptapCollabProvider } from "@hocuspocus/provider";
 
// Create a TiptapCollabProvider (you probably have this already)
const provider = new TiptapCollabProvider({
  name: "test",
  baseUrl: "https://collab.yourdomain.com",
  appId: "test",
  document: doc,
});
 
// Create a TiptapThreadStore
const threadStore = new TiptapThreadStore(
  userId, // The active user's ID
  provider, // Tiptap collaboration provider
  new DefaultThreadStoreAuth(userId, "editor"), // Authorization rules (see below)
);

ThreadStoreAuth

The ThreadStoreAuth class defines the authorization rules for interacting with comments. Every ThreadStore implementation requires a ThreadStoreAuth instance. BlockNote uses the ThreadStoreAuth instance to deterine which interactions are allowed for the current user (for example, whether they can create a new comment, edit or delete a comment, etc.).

The DefaultThreadStoreAuth class provides a basic implementation of the ThreadStoreAuth class. It takes a user ID and a role ("comment" or "editor") and implements the rules. See the source code (opens in a new tab) for more details.

Note: The ThreadStoreAuth only used to show / hide options in the UI. To secure comment related data, you still need to implement your own server-side validation (e.g. using RESTYjsThreadStore and a secure REST API).

resolveUsers function

When a user interacts with a comment, the data is stored in the ThreadStore, along with the active user ID (as specified when initiating the ThreadStore).

To display comments, BlockNote needs to retrieve user information (such as the username and avatar) based on the user ID. To do this, you need to provide a resolveUsers function in the editor options.

This function is called with an array of user IDs, and should return an array of User objects in the same order.

type User = {
  id: string;
  username: string;
  avatarUrl: string;
};
 
async function myResolveUsers(userIds: string[]): Promise<User[]> {
  // fetch user information from your database / backend
  // and return an array of User objects
 
  return await callYourBackend(userIds);
 
  // Return a list of users
  return users;
}

Sidebar View

BlockNote also offers a different way of viewing and interacting with comments, via a sidebar instead of floating in the editor, using the ThreadsSidebar component:

The only requirement for ThreadsSidebar is that it should be placed somewhere within your BlockNoteView, other than that you can position and style it however you want.

ThreadsSidebar also takes 2 props:

filter: Filter the comments in the sidebar. Can pass "open", "resolved", or "all", to only show open, resolved, or all comments. Defaults to "all".

sort: Sort the comments in the sidebar. Can pass "position", "recent-activity", or "oldest". Sorting by "recent-activity" uses the most recently added comment to sort threads, while "oldest" uses the thread creation date. Sorting by "position" puts comments in the same order as their reference text in the editor. Defaults to "position".

maxCommentsBeforeCollapse: The maximum number of comments that can be in a thread before the replies get collapsed. Defaults to 5.

See here (opens in a new tab) for a standalone example of the ThreadsSidebar component.