Skip to main content

​
Function Signature

export const removeCollaborator = async ({ roomId, email }: { roomId: string, email: string }) => Promise<Room | undefined>
Removes a collaborator’s access to a document. The document owner cannot remove themselves, and write permissions are required to remove others.

​
Parameters

​
roomId
string
required
The unique identifier of the document room.
​
email
string
required
The email address of the collaborator to remove.

​
Return Value

​
room
Room | undefined
Returns the updated room object with the collaborator removed from access, or undefined if an error occurs.

​
Usage Example

import { removeCollaborator } from '@/lib/actions/room.actions';

const handleRemoveCollaborator = async (roomId: string, collaboratorEmail: string) => {
  const updatedRoom = await removeCollaborator({
    roomId,
    email: collaboratorEmail
  });
  
  if (updatedRoom) {
    console.log('Collaborator removed:', collaboratorEmail);
  }
};

// Example usage
await handleRemoveCollaborator('room_abc123', '[email protected]');

​
Error Handling

The function enforces several validation and permission checks:
Authentication Required: User must be authenticated to remove collaborators.
// Error: "Unauthorized to remove collaborator"
if (!currentEmail) {
  throw new Error('Unauthorized to remove collaborator');
}
Write Permission Required: User must have room:write access to remove collaborators.
// Error: "Insufficient permissions to remove collaborator"
const access = room.usersAccesses[currentEmail] ?? [];
if (!access.includes('room:write')) {
  throw new Error('Insufficient permissions to remove collaborator');
}
Owner Protection: Document creators cannot remove themselves from their own documents.
// Error: "You cannot remove yourself from the document"
if (room.metadata.email === email) {
  throw new Error('You cannot remove yourself from the document');
}

​
Implementation Details

  • Null Assignment: Removes access by setting the user’s permissions to null
  • Owner Check: Compares removal target with room.metadata.email (creator)
  • Cache Revalidation: Revalidates /documents/{roomId} path
  • Permission Verification: Verifies requesting user has write access

​
Access Removal

const updatedRoom = await liveblocks.updateRoom(roomId, {
  usersAccesses: {
    [email]: null
  }
});
Setting a user’s access to null completely removes them from the document’s access control list.

​
Use Cases

Common scenarios for removing collaborators:
  • Revoking access for team members who left the project
  • Removing viewers who no longer need access
  • Managing access control as document permissions change
The document owner (creator) maintains permanent access and cannot be removed.

​
Permission Requirements

Only users with room:write permissions can remove collaborators. This typically includes:
  • Document creator (owner)
  • Collaborators with editor access
Viewers with room:read access cannot remove collaborators.
declare type RoomMetadata = {
  creatorId: string;
  email: string;
  title: string;
};

declare type RoomAccesses = Record<string, AccessType>;
declare type AccessType = ["room:write"] | ["room:read", "room:presence:write"];

​
Source

Defined in lib/actions/room.actions.ts:169

Build docs developers (and LLMs) love

Get started for freeTalk to us