Presence in DocuSphere means you always know who is viewing or editing a document at the same time as you. The moment a collaborator opens a document, their avatar appears in the toolbar. This page covers how presence works and what information is displayed.
User avatars
The document toolbar displays a stacked row of circular avatar images for every active collaborator. Each avatar shows the user’s profile picture fetched from their Clerk account. Hovering over an avatar reveals the person’s display name in a tooltip.
Your own avatar appears on the left side of the stack, labelled “You”. Other collaborators’ avatars are rendered alongside it, ordered by their connection to the room.
The avatar stack is only shown when at least one other person is present. If you are the only person in the document, the avatar row is hidden.
How presence data is resolved
When a document room is initialised, DocuSphere fetches all members of your current organization from Clerk using getUsers() (a server action that calls clerk.users.getUserList()). This list is then passed to Liveblocks’ resolveUsers callback so that every collaborator’s identity can be displayed correctly.
Each user’s presence metadata has the following shape:
UserMeta: {
id: string;
info: {
name: string; // Full name or primary email address
avatar: string; // Clerk profile image URL
color: string; // Colour associated with the user
};
}
color value is set during Liveblocks session authorization. In the /api/liveblocks-auth route, it is derived deterministically from the user’s display name — a character-code sum maps to an HSL hue, so each user gets a consistent color across sessions. This color is set via liveblocks.prepareSession with the user’s userInfo.
Cursor tracking
Liveblocks tracks each collaborator’s cursor position inside the Tiptap editor through the useLiveblocksExtension. As people move their cursors or make selections, those positions are broadcast to everyone else in the room in real time.
Presence updates instantly as people join and leave. You do not need to refresh the page — the avatar stack adds or removes avatars automatically as collaborators open or close the document.