Skip to main content
Version: Version 2.0

useRoom

The useRoom hook provides access to room functionalities, such as joining, leaving, and managing participants.

Usage​

Example:

const { room, joinRoom, leaveRoom, addComponent } = useRoom({
    onMyParticipantJoined: (participant) => console.log('Component: My participant joined', participant),
    onMyParticipantLeft: (participant) => console.log("Component: My participant left", participant),
  });

Methods​

joinRoom​

JoinRoom is the main method to join a room. Without it, you won't be able to join a room. It allows you to join a room with a specific roomId, participant, group, and debug options.

Example:

const { joinRoom } = useRoom();

const handleJoin = async () => {
  await joinRoom({
    roomId: `ROOM_ID`,
    participant: {
      id: PARTICIPANT_ID,
      name: PARTICIPANT_NAME,
      email: PARTICIPANT_EMAIL,
    },
    group: {
      name: GROUP_NAME,
      id: GROUP_ID,
    },
  });
};

return <button onClick={handleJoin}>Join Room</button>;

Parameters:

NameTypeDescription
roomIdstringRequired. This is a unique ID that you can create on your end. Using the same ID you will be able to enter the same room. Minimum length of 2 characters and maximum of 64.

Accepted pattern: [-_&@+=,()\{\}\\[\\]\/«».:|'"#a-zA-Z0-9À-ÿ\s]*
groupGroupRequired. You can organize your participants into groups. Usually, a group is a company or organization.
participantParticipantRequired. An object describing the user that will participate in the room.
debugbooleanEnable SDK logs in the browser console.
Default value: false

leaveRoom​

Call this method to leave the room.

Example:

const { leaveRoom } = useRoom();

return <button onClick={leaveRoom}>Leave Room</button>;

getParticipants​

Retrieves the list of participants in the room.

Example:

const { getParticipants } = useRoom();

getParticipants().then((participants) => {
  console.log("Participants:", participants);
});

Returns: Promise<Participant[]>

On the callback function, you will receive the following argument:

TypeDescription
Participant[]Array of participants in the room

Example:

[
  {
    "id": "USER_ID_1",
    "email": "USER_EMAIL",
    "name": "USER_NAME",
    "activeComponents": ['videoConference'],
    "type": "host",
    "avatar": {
        "imageUrl": "https://<PATH>",
    }
  },
  {
    "id": "USER_ID_2",
    "email": "USER_EMAIL",
    "name": "USER_NAME",
    "activeComponents": ['videoConference'],
    "type": "host",
    "avatar": {
        "imageUrl": "https://<PATH>",
    }
  },
];

addComponent​

The addComponent method allows you to add a component such as video conference to the room. You can add multiple components to the same room including components from SuperViz collaboration.

Example:

import { RoomProvider, useRoom, addComponent } from "@superviz/react";
import { VideoConference } from "@superviz/video";

export const Children = () => {
  const { joinRoom, addComponent } = useRoom({
    onMyParticipantJoined: () => addVideo(),
  });

  const handleJoin = async () => {
    await joinRoom({
      roomId: `ROOM_ID`,
      participant: {
        id: PARTICIPANT_ID,
        name: PARTICIPANT_NAME,
        email: PARTICIPANT_EMAIL,
      },
      group: {
        name: GROUP_NAME,
        id: GROUP_ID,
      },
    });

    const video = new VideoConference({
      participantType: 'host'
    });

    addComponent(video);
  };

  return <button onClick={handleJoin}>Join Room and add video</button>;
};

export function SupervizReactRoom() {
  return (
    <RoomProvider developerToken={SUPERVIZ_KEY}>
      <Children />
    </RoomProvider>
  );
}

Parameters:

TypeDescription
componentRequired. Pass the component instance you want to add to the room.

removeComponent​

The removeComponent method allows you to remove a component from the room.

Example:

import { RoomProvider, useRoom, removeComponent } from "@superviz/react";
import { VideoConference } from "@superviz/video";

export const Children = () => {
  const { room, joinRoom, leaveRoom, addComponent, removeComponent } = useRoom({});
  const video = useRef<VideoConference | null>(null);

  const handleJoin = async () => {
    await joinRoom({
      participant: {
        id: uuid,
        name: "Participant Name",
        email: 'carlos@superviz.com',
        avatar: {
          model3DUrl: 'https://production.storage.superviz.com/readyplayerme/1.glb',
          imageUrl: 'https://production.cdn.superviz.com/static/default-avatars/1.png',
        }
      },
      group: {
        name: SUPERVIZ_ROOM_PREFIX,
        id: SUPERVIZ_ROOM_PREFIX,
      },
      roomId: `${SUPERVIZ_ROOM_PREFIX}-${componentName}`,
      debug: true,
      environment: 'dev',
    });

    video.current = new VideoConference({
      participantType: 'host'
    });

    addComponent(video.current);
  };

  const handleLeave = () => {
    removeComponent(video.current);
    leaveRoom();
  };

  useEffect(() => {
    handleJoin();

    return () => handleLeave();
  }, [])

  return (
    <div>
      <button disabled={!!room} onClick={handleJoin}>Join Room and add video</button>
      <br />
      <button disabled={!room} onClick={handleLeave}>Leave Room and remove video</button>
    </div>
  );
};

Callbacks​

onMyParticipantJoined​

Triggered when the local participant enters the room.

Example:

const { joinRoom } = useRoom({
  onMyParticipantJoined: (participant) =>
    console.log("Component: My participant joined", participant),
});

On the callback function, you will receive the following argument:

TypeDescription
ParticipantDetails of the local participant who joined the room.

onMyParticipantLeft​

Triggered when the local participant leaves the room.

Example:

const { joinRoom } = useRoom({
  onMyParticipantLeft: (participant) =>
    console.log("Component: My participant left", participant),
});

On the callback function, you will receive the following argument:

TypeDescription
ParticipantDetails of the local participant that left the room.

onMyParticipantUpdated​

Triggered when the local participant updates.

Example:

const { joinRoom } = useRoom({
  onMyParticipantUpdated: (participant) =>
    console.log("Component: My participant updated", participant),
});

On the callback function, you will receive the following argument:

TypeDescription
ParticipantDetails of the local participant that was updated.

onParticipantJoined​

Triggered when a participant enters the room.

Example:

const { joinRoom } = useRoom({
  onParticipantJoined: (participant) =>
    console.log("Component: Participant joined", participant),
});

On the callback function, you will receive the following argument:

TypeDescription
ParticipantDetails of the participant who joined the room.

onParticipantLeft​

Triggered when a participant leaves the room.

Example:

const { joinRoom } = useRoom({
  onParticipantLeft: (participant) =>
    console.log("Component: Participant left", participant),
});

On the callback function, you will receive the following argument:

TypeDescription
ParticipantDetails of the participant who left the room.

onParticipantUpdated​

Triggered when a participant updates.

Example:

const { joinRoom } = useRoom({
  onParticipantUpdated: (participant) =>
    console.log("Component: Participant updated", participant),
});

On the callback function, you will receive the following argument:

TypeDescription
ParticipantDetails of the participant that was updated.

onRoomUpdated​

Triggered when the room updates.

Example:

const { joinRoom } = useRoom({
  onRoomUpdated: (data) => console.log("Component: Room updated", data),
});

On the callback function, you will receive the following argument:

TypeDescription
RoomStateRoom state of the room.

Example:

{
  status: "CONNECTED";
}

onError​

Triggered when an error occurs.

Example:

const { joinRoom } = useRoom({
  onError: (error) => console.error("Component: Room error", error),
});

On the callback function, you will receive the following argument:

TypeDescription
RoomErrorError details for the room operation.

Example:

{
    "code": "auth_error",
    "message": "[SuperViz] Room initialization failed: this website's domain is not whitelisted."
}

Type Definitions​

RoomError​

Type: object

An object describing the room error.

NameTypeDescription
codestringThe error code.
messagestringThe error message.

Example:

{
    "code": "auth_error",
    "message": "[SuperViz] Room initialization failed: this website's domain is not whitelisted."
}

RoomState​

Type: object

An object describing the room state.

NameTypeDescription
statusstringThe room state. Options: CONNECTED, CONNECTING, DISCONNECTED, CONNECTION_ERROR, RECONNECTING, RECONNECT_ERROR

Example:

{
    "status": "CONNECTED"
}

Participant Initialization​

Type: object

An object describing the participant information, like name and avatar.

NameTypeDescription
idstringIdentifier of the participant who is entering the room. Usually, this ID matches the internal ID of your users. Minimum length of 2 characters and maximum of 64.

Accepted pattern: [-_&@+=,()\{\}\\[\\]\/«».:|'"#a-zA-Z0-9À-ÿ\s]*
emailstringThe email of the participant who will enter the room.
namestringThe name of the participant who will enter the room.
avatarAvatarParticipant avatar information.

Example:

{
    "id": "USER_ID",
    "email": "USER_EMAIL",
    "name": "USER_NAME",
    "avatar": {
        "imageUrl": "https://<PATH>",
        "model3DUrl": "https://<PATH>",
    }
}

Participant​

Type: object

An object describing the participant information, like name and avatar.

NameTypeDescription
idstringIdentifier of the participant who is entering the room. Usually, this ID matches the internal ID of your users. Minimum length of 2 characters and maximum of 64.

Accepted pattern: [-_&@+=,()\{\}\\[\\]\/«».:|'"#a-zA-Z0-9À-ÿ\s]*
emailstringThe email of the participant who will enter the room.
activeComponentsComponentNames[]List of active components that the participant has entered.
namestringThe name of the participant who will enter the room.
avatarAvatarParticipant avatar information.

Example:

{
    "id": "USER_ID",
    "email": "USER_EMAIL",
    "name": "USER_NAME",
    "activeComponents": ['videoConference'],
    "type": "host",
    "avatar": {
        "imageUrl": "https://<PATH>",
    }
}

ComponentNames​

Type: enum

List of possible components that a participant can be added to. This is a read-only property, to add a participant into a component, you should use the addComponent method of the room. The options are:

NameValueComponent
ComponentNames.VIDEO_CONFERENCEvideoConferenceVideo Conference or Video Huddle
ComponentNames.WHO_IS_ONLINEwhoIsOnlineWho-is-Online
ComponentNames.COMMENTScommentsContextual Comments
ComponentNames.PRESENCEpresenceMouse Pointers
ComponentNames.PRESENCE_AUTODESKpresence3dAutodeskPresence 3D Autodesk
ComponentNames.PRESENCE_MATTERPORTpresence3dMatterportPresence 3D Matterport
ComponentNames.PRESENCE_THREEJSpresence3dThreejsPresence 3D Three.js

Avatar​

Type: object

Avatars represent participants within a room. In typical scenarios, they appear as profile images when used with Who-is-Online and Contextual Comments.

In 3D spaces (e.g., Matterport, Autodesk viewer or ThreeJs), avatars can take the form of 3D digital representations.

NameTypeDescription
imageUrlstringRequired. Path to the thumbnail image of the 3D model.
Supported formats: .png and .jpg.
model3DUrlstringPath to a 3D model. Only applicable when using Presence3D components
Supported formats: .glb and .gltf.

Example:

avatar: {
	imageUrl: "https://<PATH>",
	model3DUrl: "https://<PATH>",
}