Manage threads in your editor

You can use the following guide to integrate comments directly into your editor. For a full list of all Comments editor commands see the Editor Commands documentation page.

You can also interact with comments from outside your editor via our Comments REST API.

Learn about threads

Tiptap's Comments feature organizes discussions into threads for clear, context-relevant collaboration, distinguishing between threads and individual comments.

Threads are overarching containers for discussions related to specific document parts, while comments are individual contributions within those threads.

Create a new thread

Let's assume you have a button to create a new thread. You can use the setThread command to create a new thread at the current selection.

const createThread = () => {
  editor
    .chain()
    .setThread({
      content: 'This is a new thread', // the content of the threads first inital comment
    })
    .run()
}

This will create a new thread at the current selection and add a comment with the given content. By default comments and threads don't have a user or any other meta data assigned. Lets say you want to add the author to the thread and the comment. You can do this by passing through the data and commentData property to the setThread command.

const createThread = () => {
  const user = {
    id: '123', // the user id of the author
    name: 'John Doe', // the name of the author
    avatarUrl: 'https://example.com/avatar.jpg', // the avatar of the author
  }

  editor
    .chain()
    .setThread({
      content: 'This is a new thread', // the content of the threads first inital comment
      data: {
        user,
      },
      commentData: {
        user,
      },
    })
    .run()
}

Now the thread and comment will have a user assigned to it.

Receive and render threads

To receive the list of threads on your current document, you can simply call provider.getThreads(). This will return an array of threads on the document connected to your provider.

This is a static array which won't update on its own. If you want to keep the list of threads up to date, you can listen to changes via the provider.watchThreads and provider.unwatchThreads functions.

// lets save threads in a variable
let threads = []

// this function is called whenever the threads change
const getThreads = () => {
  threads = provider.getThreads()
}

// initial call to get the threads
getThreads()

// watch for changes
provider.watchThreads(getThreads)

to unwatch the threads you can call provider.unwatchThreads(getThreads).

provider.unwatchThreads(getThreads)

Lets say you want to write a react hook to get the threads and keep them up to date, you could write a hook like this.

const useThreads = (provider) => {
  const [threads, setThreads] = useState([])

  useEffect(() => {
    if (!provider) {
      return () => null
    }

    const getThreads = () => {
      setThreads(provider.getThreads())
    }

    getThreads()

    provider.watchThreads(getThreads)

    return () => {
      provider.unwatchThreads(getThreads)
    }
  }, [provider])

  return threads
}

Now those threads will be reactive and can be used to render the threads in your UI.

Update a thread

To update a thread you can use the updateThread command. This command will update the thread with the given id and update the content of the thread.

editor.commands.updateThread({
  id: '123',
  {
    data: {
      seen: true,
    }
  }
})

This will update the thread with the id 123 and set the seen property to true.

Delete a thread

To delete a thread you can use the removeThread command. This command will delete the thread with the given id.

editor.commands.removeThread({
  id: '123',
  deleteThread: true,
})

Create, update and delete comments

Comments can be added, edited, and removed within threads but cannot be marked as resolved, as they are considered parts of the thread discussions.

To create a comment on a thread you can use the createComment command. This command will create a new comment on the thread with the given id.

editor.commands.createComment({
  threadId: '123',
  content: 'This is a new comment', // this could also be tiptap JSON or any other type of content
  data: {
    user, // pass through any meta data you want - in this case the user
  },
})

This will create a new comment on the thread with the id 123 and set the content to This is a new comment. You can also pass through any meta data you want to the comment.

To update a comment you can use the updateComment command. This command will update the comment with the given id and update the content of the comment.

editor.commands.updateComment({
  threadId: '123', // the thread ID
  id: '456', // the comment ID
  content: 'Now this is the new content', // the new content of the comment
  data: {
    edited: true, // set the edited property to true
  },
})

This will update the comment with the id 456 on the thread with the id 123 and set the content to Now this is the new content. You can also pass through any meta data you want to the comment.

Finally you can delete a comment by using the deleteComment command. This command will delete the comment with the given id.

editor.commands.deleteComment({
  threadId: '123',
  id: '456',
})

Resolve and unresolve threads

To resolve a thread you can use the resolveThread command. This command will resolve the thread with the given id.

editor.commands.resolveThread({
  id: '123',
})

This will resolve the thread with the id 123. To unresolve a thread you can use the unresolveThread command. This command will unresolve the thread with the given id.

If you want to resolve a thread and add information on which user resolved the thread, you can set the threads data to include the user who resolved the thread. Just make sure to clear the data when unresolving the thread.

editor.commands.unresolveThread({
  id: '123',
})

Select a thread

To select a thread you can use the selectThread command. This command will select the thread with the given id.

editor.commands.selectThread({
  id: '123',
})

This will move the cursor to the thread with the id 123.

To deselect a thread you can use the unselectThread command. This command will deselect the thread with the given id.

editor.commands.unselectThread({
  id: '123',
})

You can also select or unselect threads without an id. In that case, the editor will select or unselect the thread at the current selection.