Skip to main content

​
Overview

The getDocumentUsers function retrieves a list of user email addresses that have access to a specific Liveblocks room (document). It supports optional text filtering and includes authorization checks.

​
Function Signature

export const getDocumentUsers = async ({ 
  roomId, 
  currentUser, 
  text 
}: { 
  roomId: string, 
  currentUser: string, 
  text: string 
})

​
Parameters

​
roomId
string
required
The Liveblocks room ID representing the document
​
currentUser
string
required
Email address of the current authenticated user. Used for authorization verification.
​
text
string
required
Filter text to search for users. If empty string is provided, returns all users. The search is case-insensitive and matches email addresses containing the text.

​
Return Value

​
emails
string[] | undefined
Array of email addresses for users with access to the room, excluding the current user. Returns undefined if an error occurs.
  • If text parameter is provided and has length > 0, returns filtered emails matching the search text
  • If text is empty, returns all user emails with access to the room
  • Current user’s email is always excluded from results

​
Code Example

​
Fetch All Document Users

import { getDocumentUsers } from '@/lib/actions/user.actions';

// Get all users with access to a document
const documentUsers = await getDocumentUsers({
  roomId: 'room-123',
  currentUser: '[email protected]',
  text: '' // Empty string returns all users
});

if (documentUsers) {
  console.log('Document collaborators:', documentUsers);
  // ['[email protected]', '[email protected]', '[email protected]']
}

​
Filter Users by Text

import { getDocumentUsers } from '@/lib/actions/user.actions';

// Search for users containing 'john' in their email
const filteredUsers = await getDocumentUsers({
  roomId: 'room-123',
  currentUser: '[email protected]',
  text: 'john' // Case-insensitive search
});

if (filteredUsers) {
  console.log('Matching users:', filteredUsers);
  // ['[email protected]', '[email protected]']
}

​
Error Handling

The function handles errors gracefully and logs them to the console. It returns undefined when:
  • The current user is not authenticated
  • The currentUser parameter doesn’t match the authenticated user’s email
  • The Liveblocks room doesn’t exist or cannot be accessed
  • Any other error occurs during execution
This is a server action and must be called from server components or other server actions. The function verifies that the authenticated user matches the currentUser parameter for security.

​
Authorization

The function performs two levels of authorization:
  1. Checks if a user is currently authenticated via Clerk
  2. Verifies that the authenticated user’s email matches the currentUser parameter
If either check fails, it throws an “Unauthorized to list document users” error.

​
Implementation Details

  • Uses liveblocks.getRoom() to fetch room data and access permissions
  • Extracts user emails from room.usersAccesses object keys
  • Excludes the current user from the results
  • Performs case-insensitive filtering when text is provided
  • Uses parseStringify utility for serialization

​
Use Cases

  • Displaying a list of document collaborators
  • Implementing user search/autocomplete in share dialogs
  • Filtering collaborators by email pattern
  • Managing document access permissions

Build docs developers (and LLMs) love

Get started for freeTalk to us