useRoomConnection

The useRoomConnection hook provides the ability to connect participants in a given room, subscribe to state updates, and perform actions on the connection like toggling the camera or microphone.

useRoomConnection(roomUrl: string, roomConnectionOptions: RoomConnectionOptions): Object | null

ParameterRequiredTypeDescription

roomUrl

string

The URL of the Whereby room. Refer to our REST api reference to learn how to create these.

roomConnectionOptions

Additional options for the room connection

Return type

The hook returns a RoomConnectionReference object with the following properties.

PropertyTypeDescription

state

Object representing the state of the room

actions

Object representing the available actions in the room

components

Object representing the pre-bound components available for the room

state

The current state of the room. Use this state to render your custom video experience.

PropertyTypeDescription

chatMessages

The chat messages which have been sent in the room since connecting.

cloudRecording

Indicates whether cloud recording is active in the room.

connectionStatus

Overall status of the room connection

localScreenshareStatus

Status of your local screen share

localParticipant

A representation of the local participant in the call (you)

remoteParticipants

RemoteParticipant[]

A list of the remote participants in the room

screenshares

List of active screenshares in the room

liveStream

Set if live stream is enabled for the room

waitingParticipants

A list of participants waiting to enter a locked room.

actions

The actions property contains a map of functions which can be invoked to perform an action in the room. All these functions are sync and return void, and you should rely on the state to render the effect of their invocation.

PropertyTypeDescription

sendChatMessage

(text: string) => void

Send a chat message to the room

() => void

Let the room host know that the local participant is waiting and wants to join

setDisplayName

(displayName: string) => void

Change your display name

toggleCamera

(enabled?: boolean) => void

Change the state of your camera

toggleMicrophone

(enabled?: boolean) => void

Change the state of your microphone

acceptWaitingParticipant

(participantId: string) => void

Accept waiting participant

rejectWaitingParticipant

(participantId: string) => void

Reject waiting participant

startScreenshare

() => void

Start screen share

stopScreenshare

() => void

Stop screen share

(locked: boolean) => void

[Host only] Lock (true) or unlock (false) the current room

(participantIds: string[]) => void

[Host only] Mute participants.

components

Components are JSX elements bound to the room connection to make it easier for you to render

PropertyTypeDescription

VideoView

A React component to be used for rendering the participant video and audio.

Usage

import { useRoomConnection } from "@whereby.com/browser-sdk/react";

function MyCallUX( { roomUrl, localStream }) {
    const { state, actions, components } = useRoomConnection(
        "<room_url>"
        {
            localMediaOptions: {
                audio: true,
                video: true,
            }
        }
    );

    const { connectionState, remoteParticipants } = state;
    const { toggleCamera, toggleMicrophone } = actions;
    const { VideoView } = components;

    return <div className="videoGrid">
        { /* Render any UI, making use of state */ }
        { remoteParticipants.map((p) => (
            <VideoView key={p.id} stream={p.stream} />
        )) }
    </div>;
}

Last updated