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

"use client";
 
import { DefaultThreadStoreAuth, YjsThreadStore } from "@blocknote/core";
import { BlockNoteView } from "@blocknote/mantine";
import "@blocknote/mantine/style.css";
import { useCreateBlockNote } from "@blocknote/react";
import { MantineProvider, Select } from "@mantine/core";
import { YDocProvider, useYDoc, useYjsProvider } from "@y-sweet/react";
import { useMemo, useState } from "react";
import { HARDCODED_USERS, MyUserType, getRandomColor } from "./userdata";
 
// The resolveUsers function fetches information about your users
// (e.g. their name, avatar, etc.). Usually, you'd fetch this from your
// own database or user management system.
// Here, we just return the hardcoded users (from userdata.ts)
async function resolveUsers(userIds: string[]) {
  // fake a (slow) network request
  await new Promise((resolve) => setTimeout(resolve, 1000));
 
  return HARDCODED_USERS.filter((user) => userIds.includes(user.id));
}
 
// This follows the Y-Sweet example to setup a collabotive editor
// (but of course, you also use other collaboration providers
// see the docs for more information)
export default function App() {
  const docId = "my-blocknote-document-with-comments";
 
  return (
    <MantineProvider>
      <YDocProvider
        docId={docId}
        authEndpoint="https://demos.y-sweet.dev/api/auth">
        <Document />
      </YDocProvider>
    </MantineProvider>
  );
}
 
function Document() {
  const [user, setUser] = useState<MyUserType>(HARDCODED_USERS[0]);
  const provider = useYjsProvider();
 
  // take the Y.Doc collaborative document from Y-Sweet
  const doc = useYDoc();
 
  // setup the thread store which stores / and syncs thread / comment data
  const threadStore = useMemo(() => {
    // (alternative, use TiptapCollabProvider)
    // const provider = new TiptapCollabProvider({
    //   name: "test",
    //   baseUrl: "https://collab.yourdomain.com",
    //   appId: "test",
    //   document: doc,
    // });
    // return new TiptapThreadStore(
    //   user.id,
    //   provider,
    //   new DefaultThreadStoreAuth(user.id, user.role)
    // );
    return new YjsThreadStore(
      user.id,
      doc.getMap("threads"),
      new DefaultThreadStoreAuth(user.id, user.role)
    );
  }, [doc, user]);
 
  // setup the editor with comments and collaboration
  const editor = useCreateBlockNote(
    {
      resolveUsers,
      comments: {
        threadStore,
      },
      collaboration: {
        provider,
        fragment: doc.getXmlFragment("blocknote"),
        user: { color: getRandomColor(), name: user.username },
      },
    },
    [user, threadStore]
  );
 
  return (
    <div>
      {/* This is a simple user selector to switch between users, for demo purposes */}
      <Select
        style={{ maxWidth: "300px" }}
        required
        label="Active user:"
        placeholder="Pick value"
        data={HARDCODED_USERS.map((user) => ({
          value: user.id,
          label: user.username + " (" + user.role + ")",
        }))}
        onChange={(value) => {
          if (!value) {
            return;
          }
          setUser(HARDCODED_USERS.find((user) => user.id === value)!);
        }}
        value={user.id}
      />
      {/* render the actual editor */}
      <BlockNoteView editor={editor} editable={user.role === "editor"} />
    </div>
  );
}
 

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