How to add users to Liveblocks Comments

After following the get started guide for Comments, you’ll notice that each useris currently “Anonymous”, and that there’s no way to mention or tag other users.To enable these features, we need to tell Comments where to find your users’information.

What we’re learning

In this guide we’ll be modifyingLiveblocksProvider,learning how to:

• Add names and avatars to threads and comments withresolveUsers.
• Create user mention suggestions in the composer usingresolveMentionSuggestions.

Authenticate your application

The first step is to find anauthentication guide for your framework and authenticateyour app, as this is necessary for Comments.

Make sure to follow the metadata step in the guide, and attach the name of youruser, along with the URL of their avatar, as these properties will both be usedin thedefault components.Here’s an example using access token authentication, with an email address as auser’s ID.

const session= liveblocks.prepareSession("marc@example.com",{  userInfo:{    name:"Marc",    avatar:"https://example.com/marc.png",
// Your custom metadata// ...},});

If you’re using ID token authentication, it’ll look a little different.

Don’t forget to modify yourUserMeta type inliveblocks.config.ts to matchthe metadata format, adding type hints to your editor.

declare global{interfaceLiveblocks{    UserMeta:{      id:string;
      info:{        name:string;        avatar:string;
// Your custom metadata// ...};};}}

Resolving users

To show each user’s name and avatar in threads and comments, we need to useresolveUsers.

1. Add the function to your LiveblocksProvider

   TheresolveUsers function is passed as an option toLiveblocksProvider—let’s add it. This functionprovides you withuserIds, an array of user IDs that have interacted with Comments.TheseuserIds match the IDs set when authenticating users in your app.

   <LiveblocksProviderresolveUsers={async({ userIds})=>{// ["marc@example.com", ...]console.log(userIds);
   // Return a list of users// ...}}
   // .../>;

2. Return your users

   resolveUsers requires you to return a list of users intheUserMeta["info"] format we set earlier. Rememberthatname andavatar are required for the default components,but you can also use any other metadata in your app.

   <LiveblocksProviderresolveUsers={async({ userIds})=>{// ["marc@example.com", ...]console.log(userIds);
   // Return a list of usersreturn[{        name:"Marc",        avatar:"https://example.com/marc.png",
   // Your custom metadata// ...},// ...];}}
   // .../>;

   We’re only returning one user here, but make sure to return anarray containing each user, in the same order you received the IDs.

3. Real-world example

   In your real application you’ll probably be getting users from yourAPI endpoint and database viafetch. This is how we’d recommendbuilding out this function.

   <LiveblocksProviderresolveUsers={async({ userIds})=>{// Get users from your back endconst users=await__fetchUsers__(userIds);
   // Return a list of usersreturn users;}}
   // .../>;

4. Users are now visible

   After adding this, you should now be able to see your users in threads!

   

Resolving mention suggestions

We can see the users that have commented, but we don’t have a way to search forusers to mention, for example after typing the@ character. We can create asimple search that resolves this data withresolveMentionSuggestions.

1. Add the function to your config file

   resolveMentionSuggestions is placed alongsideresolveUsers, andprovides you withtext, which is the string that the user is searching for.You can use this string to return a list of matching user IDs.

   <LiveblocksProviderresolveUsers={async({ userIds})=>{// ...}}resolveMentionSuggestions={async({ text, roomId})=>{// The text the user is searching for, e.g. "mar"console.log(text);
   // Return a list of user IDs that match the queryreturn["marc@example.com","marissa@example.com"];}}
   // .../>;

2. Real-world example

   In a real application, you’ll most likely be getting a list of each user,before filtering the list by the user’s names or IDs. Iftext is an emptystring, then you need to return a list of every user, instead of a filtered list.

   <LiveblocksProviderresolveUsers={async({ userIds})=>{// ...}}resolveMentionSuggestions={async({ text, roomId})=>{// Fetch all users from your back endlet users=await__fetchAllUsers__();
   // If there's a query, filter for the relevant usersif(text){// Filter any way you'd like, e.g. checking if the name matches      users= users.filter((user)=> user.name.includes(text));}
   // Return the filtered `userIds`return users.map((user)=> user.id);}}
   // .../>;

3. Mention suggestions now appear

   Now we’ve found and returned the correct users, Comments can displaya list of mention suggestions!

   

Next steps

You’re now ready to start building your Comments application! Here’s where youcan learn more:

• API reference
• Component reference
• Examples

Related guides

• How to send email notifications for unread text editor mentions

  November 29, 2024
  • Text editors
  • Tutorials
  • Webhooks
  • Notifications
  • React UI
  • Node.js
  • Lexical
  • Tiptap

• Revalidate API data in realtime with SWR

  May 26, 2023
  • Data fetching
  • React
  • Next.js