Comments - Users and mentions

When a comment is posted, Liveblocks doesn’t store any user or group metadata, for example their avatar or name. Instead, it only saves their user ID, which you manually set when authenticating. To fetch user and group metadata, we provide functions that allow you to return the correct data.

Step-by-step tutorial

This page explains the concepts behind adding users and mentions to Comments. If you’d prefer a full step-by-step tutorial, make sure to read how to add users to Liveblocks Comments.

Authenticate your users

You can set a user’s ID when authenticating your application, for example with liveblocks.prepareSession. This ID is then used inside Comments to represent the current user, for example we’re using an email address as a user ID below.

const session = liveblocks.prepareSession("charlie.layne@example.com", {  userInfo: {    // Custom user info to be used in Presence    // This is NOT used in Comments    // ...  },});

There are two different authentication methods—make sure to follow an authentication guide for your framework to get started.

Adding user information to Comments

In Comments, user information is retrieved from a list of user IDs, for example here’s a userIds array and the information you need to return. You should return the same number of users as the number of user IDs, in the same order.

# If this is `userIds`["marc@example.com", "pierre@example.com"]
# Return `users`[{ name: "Marc", avatar: "https://example.com/marc.png" }, { name: "Pierre", avatar: "https://example.com/pierre.png" }]

Add a property named resolveUsers to your LiveblocksProvider where you can return this information.

<LiveblocksProvider  authEndpoint="/api/liveblocks-auth"  resolveUsers={async ({ userIds }) => {    // ["marc@example.com", ...]    console.log(userIds);
    // Get users from your back end    const users = await (userIds);
    // [{ name: "Marc", avatar: "https://example.com/marc.png" }, ...]    console.log(users);
    // Return a list of users    return users;  }}>

The name, and avatar are handled by the default components, but you can also return custom metadata here. For example, each user may have a color property. You can retrieve these properties in your app with useUser.

function Component() {  const { user } = useUser("marc@example.com");
  // { color: "red", name: "Marc", avatar: "https://example.com/marc.png" }  console.log(user);
  // ...}

Adding group information to Comments

You can also adds groups to Comments, allowing you to tag a team of people with one mention. Similar to users, group information is retrieved from a list of group IDs. You should return the same number of groups as the number of group IDs, in the same order.

# If this is `groupIds`["engineering", "design"]
# Return `groups`[{ name: "Engineering", avatar: "https://example.com/engineering.png" }, { name: "Design", avatar: "https://example.com/design.png" }]

Add a property named resolveGroupsInfo to your LiveblocksProvider where you can return this information.

<LiveblocksProvider  authEndpoint="/api/liveblocks-auth"  resolveGroupsInfo={async ({ groupIds }) => {    // ["engineering", ...]    console.log(groupIds);
    // Get groups from your back end    const groups = await (groupIds);
    // [{ name: "Engineering", avatar: "https://example.com/engineering.png" }, ...]    console.log(groups);
    // Return a list of groups    return groups;  }}>

The name and avatar are handled by the default components, but you can also also return custom metadata here. For example, each group may have a color property. You can retrieve these properties in your app with useGroupInfo.

function Component() {  const { group } = useGroupInfo("engineering");
  // { color: "blue", name: "Engineering", avatar: "https://example.com/engineering.png" }  console.log(group);
  // ...}

Resolving user and group mentions suggestions

Comments allows you to search for users and groups after typing the "@" character.

When a user types "@" and searches for a user or group, Comments will pass you a text property which you can use to return matching user IDs and group IDs.

# If "@mar" has been typed, this is `text`"mar"
# Return matching `userIds` and `groupIds`["marc@example.com", "marissa@example.com"]

You can resolve these search results by adding a resolveMentionSuggestions property to your LiveblocksProvider. Here's what the function might look like if the user has typed "@mar" into the input.

User mentions only

<LiveblocksProvider  authEndpoint="/api/liveblocks-auth"  resolveUsers={async ({ userIds }) => {    // ...  }}  resolveMentionSuggestions={async ({ text, roomId }) => {    // "mar"    console.log(text);
    // Return an array of user IDs for the query "mar"    let userIds;
    if (text) {      // If there's a query, get user IDs from your back end that match      userIds = await (text);    } else {      // If there's no query, get all of the room's user IDs      userIds = await ();    }
    // ["marc@example.com", "marissa@example.com"]    console.log(userIds);    return userIds;  }}>

User and group mentions

To support both user and group mentions, you can return a list of mention objects instead of just user IDs. This allows you to suggest a mix of users and groups.

<LiveblocksProvider  authEndpoint="/api/liveblocks-auth"  resolveUsers={async ({ userIds }) => {    // ...  }}  resolveGroupsInfo={async ({ groupIds }) => {    // ...  }}  resolveMentionSuggestions={async ({ text, roomId }) => {    // "mar"    console.log(text);
    let userIds;    let groupIds;
    if (text) {      // If there's a query, get user and groups IDs from your back end that match      userIds = await (text);      groupIds = await (text);    } else {      // If there's no query, get all of the room's user and group IDs      userIds = await ();      groupIds = await _getAllGroupIds__();    }
    // Show groups and users matching the text being typed    return [      ...groupIds.map((group) => ({        kind: "group",        id: group.id,      })),      ...userIds.map((user) => ({        kind: "user",        id: user.id,      })),    ];  }}>

If a user has only typed "@", text is an empty string, and it's recommended to return every user and group.