How to add users to Liveblocks presence components

After following the get started guide for presence components, 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 Liveblocks where to find your users’ information.

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 adding users. Here’s an example using ID token authentication, our recommended method, with an email address as a user’s ID.

Metadata in ID tokens

const { status, body } = await liveblocks.identifyUser({
    userId: "marc@example.com",
    // Optional
    // organizationId: "org-id",
    // groupIds: ["group-id-1", "group-id-2"],
}, {
    userInfo: {
        // Optional, custom metadata
        // ...
    },
});

Resolving users

To show each user’s name and avatar in the ready-made AvatarStack and Cursors components, we need to use resolveUsers.

  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 Comments. 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
    // ...
  }}
  // .../>

  1. Return your users

resolveUsers requires you to return a list of users in the UserMeta["info"] format we set earlier. Remember that name and avatar are required for the default components, 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",
        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.

  1. 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 __fetchUsers__(userIds);
    // Return a list of users
    return users;
  }}
  // .../>

  1. Render the presence components

Import the presence components in your app to see them. Cursors wraps around the component where the cursors will appear.

import { AvatarStack, Cursors } from "@liveblocks/react-ui";
function App() {
  return (
    <Cursors style={{ width: "100vw", height: "100vh" }}>
      <AvatarStack />
      {/* Rest of your app here */}
    </Cursors>
  );
}

  1. Users are now visible

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

Next steps

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