Comments - Concepts

A quick overview of the concepts used in Liveblocks Comments.

Threads

In Liveblocks Comments, everything revolves around threads. In each multiplayer room you can create a number of threads. Each individual thread contains a list of comments written by your users.

Threads can be retrieved by a React hook or on your server. Here’s an example of a thread object.

{  type: "thread",  id: "th_sf8s6sh...",  roomId: "my-room-id",  createdAt: Date <Fri Dec 15 2023 14:15:22 GMT+0000 (Greenwich Mean Time)>,  comments: [    // A list of comments in the thread    // ...  ],  metadata: {    // Your custom thread metadata    // ...  },}

Threads can also store custom metadata, which is helpful for integrating them into your product.

Comments

Each comment is created by a user, referenced by their user ID, and is part of a thread. The first comment in a thread is displayed at the top.

Here’s an example of a single comment inside a thread object.

{  type: "thread",  id: "th_sf8s6sh...",  roomId: "my-room-id",  createdAt: Date <Fri Dec 15 2023 14:15:22 GMT+0000 (Greenwich Mean Time)>,  comments: [    {      type: "comment",      threadId: "th_sf8s6sh...",      id: "cm_agH76a...",      roomId: "my-room-id",      userId: "alicia@example.com",      createdAt: Date <Fri Dec 15 2023 14:15:22 GMT+0000 (Greenwich Mean Time)>,      editedAt: Date <Fri Dec 15 2023 15:07:19 GMT+0000 (Greenwich Mean Time)>,      body: {        // The comment's text in `CommentBody` format        // ...      },    },
    // Other comments in the thread    // ...  ],  metadata: {    // Your custom thread metadata    // ...  },}

A comment’s body is in a custom CommentBody format, though you most likely won’t need to use this, as we render it in React for you. We also provide a number of functions that allow you to easily convert a comment’s body into Markdown, HTML, or plain text, which is especially helpful for creating email notifications.

Deleted comments

Deleting a comment doesn’t remove the comment object from the thread, instead the comment.body property is removed, and a comment.deletedAt property is added, which contains the deletion time. This allows you to handle the deleted comment in whichever way you see fit, for example you may like to create a “message deleted” placeholder for the comment. Alternatively, the comment can be hidden completely.

A thread is only deleted after all its comments have been deleted.