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

Parameter	Required	Type	Description
roomUrl	✅	string	The URL of the Whereby room. Refer to our REST api reference to learn how to create these.
roomConnectionOptions	✅	RoomConnectionOptions	Additional options for the room connection

Return type

The hook returns a RoomConnectionReference object with the following properties.

Property	Type	Description
state	RoomConnectionState	Object representing the state of the room
actions	RoomConnectionActions	Object representing the available actions in the room
components	RoomConnectionComponents	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.

Property	Type	Description
chatMessages	ChatMessage[]	The chat messages which have been sent in the room since connecting.
cloudRecording	CloudRecordingState	Indicates whether cloud recording is active in the room.
connectionStatus	RoomConnectionStatus	Overall status of the room connection
localScreenshareStatus	LocalScreenshareStatus?	Status of your local screen share
localParticipant	LocalParticipant?	A representation of the local participant in the call (you)
remoteParticipants	RemoteParticipant[]	A list of the remote participants in the room
screenshares	Screenshare[]	List of active screenshares in the room
liveStream	LiveStreamState?	Set if live stream is enabled for the room
waitingParticipants	WaitingParticipant[]	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.

Property	Type	Description
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
toggleLowDataMode	(enabled?: boolean) => void	Change the state of low data mode
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 remote participants
	(participantId: string) => void	[Host only] Remove the specified remote participant from the meeting
	() => void	[Host only] End the meeting for all remote participants

components

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

Property	Type	Description
VideoView	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>;
}