How to add users to Liveblocks Text Editor

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

User mentions

What we’re learning

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

Authenticate your application

The first step is to find an authentication guide for your framework and authenticate your app, as this is necessary for Text Editor.

Make sure to follow the metadata step in the guide, and attach the name of your user, the color of their cursor, and their avatar URL, as these properties will both be used in the Text editor. Here’s an example using access token authentication, with an email address as a user’s ID.

Metadata in access tokens
const session = liveblocks.prepareSession("marc@example.com", {  userInfo: {    name: "Marc",    color: "#00ff00",    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 your UserMeta type in liveblocks.config.ts to match the metadata format, adding type hints to your editor.

liveblocks.config.ts
declare global {  interface Liveblocks {    UserMeta: {      id: string;
info: { name: string; color: string; avatar: string;
// Your custom metadata // ... }; }; }}

Resolving users

To show each user’s name and color in their cursors, we need to use resolveUsers.

Real-time text cursors
  1. Add the function to your LiveblocksProvider

    The resolveUsers function is passed as an option to LiveblocksProvider—let’s add it. This function provides you with userIds, an array of user IDs that have interacted with Text Editor. These userIds match the IDs set when authenticating users in your app.

    <LiveblocksProvider  resolveUsers={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 in the UserMeta["info"] format we set earlier. Remember that name, color, and avatar, are required for the editor component, but you can also use any other metadata in your app.

    <LiveblocksProvider  resolveUsers={async ({ userIds }) => {    // ["marc@example.com", ...]    console.log(userIds);
    // Return a list of users return [ { name: "Marc", color: "#00ff00", avatar: "https://example.com/marc.png",
    // Your custom metadata // ... }, // ... ]; }}
    // .../>;

    We’re only returning one user here, but make sure to return an array 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 your API endpoint and database via fetch. This is how we’d recommend building out this function.

    <LiveblocksProvider  resolveUsers={async ({ userIds }) => {    // Get users from your back end    const users = await (userIds);
    // Return a list of users return users; }}
    // .../>;
  4. Users are now visible

    After adding this, you should now be able to see your user names in cursors!

    Real-time text cursors

Resolving mention suggestions

We can see the users that are connected, but we don’t have a way to search for users to mention inline, for example after typing the @ character. We can create a simple search that resolves this data with resolveMentionSuggestions.

User mentions
  1. Add the function to your config file

    resolveMentionSuggestions is placed alongside resolveUsers, and provides you with text, which is the string that the user is searching for. You can use this string to return a list of matching user IDs.

    <LiveblocksProvider  resolveUsers={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 query return ["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. If text is an empty string, then you need to return a list of every user, instead of a filtered list.

    <LiveblocksProvider  resolveUsers={async ({ userIds }) => {    // ...  }}  resolveMentionSuggestions={async ({ text, roomId }) => {    // Fetch all users from your back end    let users = await ();
    // If there's a query, filter for the relevant users if (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, Text Editor can display a list of mention suggestions!

    User mentions

Next steps

You’re now ready to start building your Text Editor application! Here’s where you can learn more: