> For the complete documentation index, see [llms.txt](https://docs.whereby.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.whereby.com/reference/react-hooks-reference/useroomconnection.md).

# 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`

<table><thead><tr><th width="234">Parameter</th><th width="103">Required</th><th width="275">Type</th><th>Description</th></tr></thead><tbody><tr><td>roomUrl</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td><code>string</code></td><td>The URL of the Whereby room. Refer to our <a href="https://docs.whereby.com/whereby-rest-api-reference#meetings">REST api reference</a> to learn how to create these.</td></tr><tr><td>roomConnectionOptions</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td><a href="/reference/react-hooks-reference/types.md#roomconnectionoptions"><code>RoomConnectionOptions</code></a></td><td>Additional options for the room connection</td></tr></tbody></table>

## Return type

The hook returns a `RoomConnectionReference` object with the following properties.

<table><thead><tr><th>Property</th><th width="279.3333333333333">Type</th><th>Description</th></tr></thead><tbody><tr><td>state</td><td><a href="#state"><code>RoomConnectionState</code></a></td><td>Object representing the state of the room</td></tr><tr><td>actions</td><td><a href="#actions"><code>RoomConnectionActions</code></a></td><td>Object representing the available actions in the room</td></tr><tr><td>events</td><td><a href="#events">RoomConnectionEvents</a></td><td>Event emitter that emits in-room events as they are happening</td></tr></tbody></table>

### state

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

| Property                | Type                                                                                                                              | Description                                                                                                                                                              |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| chatMessages            | [`ChatMessage[]`](/reference/react-hooks-reference/types.md#chatmessage)                                                          | The chat messages which have been sent in the room since connecting                                                                                                      |
| cloudRecording          | [`CloudRecordingState`](/reference/react-hooks-reference/types.md#cloudrecordingstate)`?`                                         | Indicates whether cloud recording is active in the room                                                                                                                  |
| connectionStatus        | [`RoomConnectionStatus`](/reference/react-hooks-reference/types.md#roomconnectionstatus)                                          | Overall status of the room connection                                                                                                                                    |
| localScreenshare        | [<mark style="color:blue;">`LocalScreenshareState`</mark>](/reference/react-hooks-reference/types.md#localscreensharestatus-2)`?` | Indicates whether local screensharing is active in the room                                                                                                              |
| localParticipant        | [`LocalParticipant`](/reference/react-hooks-reference/types.md#localparticipant)`?`                                               | A representation of the local participant in the call (you)                                                                                                              |
| liveTranscription       | [`LiveTranscriptionState`](/reference/react-hooks-reference/types.md#localscreensharestatus)`?`                                   | Indicates whether live transcription is active in the room                                                                                                               |
| liveCaptions            | [`LiveCaptionsState`](/reference/react-hooks-reference/types.md#localscreensharestatus-1)`?`                                      | Indicates whether live captions is active in the room and provides access to ongoing live caption data                                                                   |
| remoteParticipants      | [`RemoteParticipant`](/reference/react-hooks-reference/types.md#remoteparticipant)`[]`                                            | A list of the remote participants in the room                                                                                                                            |
| screenshares            | [`Screenshare`](/reference/react-hooks-reference/types.md#screenshare)`[]`                                                        | List of active screenshares in the room                                                                                                                                  |
| liveStream              | [<mark style="color:blue;">`LiveStreamState`</mark>](/reference/react-hooks-reference/types.md#livestreamstate)`?`                | Set if live stream is enabled for the room                                                                                                                               |
| waitingParticipants     | [`WaitingParticipant`](/reference/react-hooks-reference/types.md#waitingparticipant)`[]`                                          | A list of participants waiting to enter a locked room                                                                                                                    |
| spotlightedParticipants | [ClientView](/reference/react-hooks-reference/types.md#clientview)\[]                                                             | A list of spotlighted participants                                                                                                                                       |
| breakout                | [Breakout](/reference/react-hooks-reference/types.md#breakout)                                                                    | The breakout group state of the room                                                                                                                                     |
| knockResponse           | `KnockResponse \| null`                                                                                                           | The host's response to your knock when you were put on hold or rejected. `null` until a response arrives, and it may carry no message, guard on `knockResponse?.message` |

### 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.

<table><thead><tr><th width="205.90755208333331">Property</th><th width="324.72265625">Type</th><th>Description</th></tr></thead><tbody><tr><td>joinRoom</td><td><code>() => Promise&#x3C;</code><a href="/reference/core-sdk-reference/types/roomconnection-types.md#roomjoinedsuccess-less-than-object-greater-than"><code>RoomJoinedSuccess</code></a><code>></code></td><td>Join the room configured in the <a href="/reference/react-hooks-reference/useroomconnection.md"><code>useRoomConnection</code></a> config.</td></tr><tr><td><a data-footnote-ref href="#user-content-fn-1">knock</a></td><td><code>() => void</code></td><td>Let the room host know that the local participant is waiting and wants to join</td></tr><tr><td>setDisplayName</td><td><code>(displayName: string) => void</code></td><td>Change your display name</td></tr><tr><td>sendChatMessage</td><td><code>(text: string, parentId?: string) => void</code></td><td><p>Send a chat message to the room.</p><p></p><p>If <code>parentId</code> is provided and matches the <code>id</code> of a previously received chat message then the chat message will be sent as a <em>reply</em> to the original chat message.</p></td></tr><tr><td>removeChatMessage</td><td><code>(id: string, sig?: string | null)</code></td><td><p>Mark a chat message with <code>removed: true</code> in the rooms state's <code>chatMessages</code>. </p><p></p><p>To remove a chat message, a <code>sig</code> provided in a previously sent ChatMessage must be included.</p><p></p><p>Hosts can remove any chat message without needing to send any <code>sig.</code></p></td></tr><tr><td>toggleCamera</td><td><code>(enabled?: boolean) => void</code></td><td>Change the state of your camera</td></tr><tr><td>toggleMicrophone</td><td><code>(enabled?: boolean) => void</code></td><td>Change the state of your microphone</td></tr><tr><td>toggleHdMode</td><td><code>(enabled?: boolean) => void</code></td><td>Change the state of video quality between high-definition and standard-definition. Default <code>true</code></td></tr><tr><td>toggleLowDataMode</td><td><code>(enabled?: boolean) => void</code></td><td>Change the state of low data mode</td></tr><tr><td>toggleWidescreenMode</td><td><code>(enabled?: boolean) => void</code></td><td>Change the state of video width/height between 16:9 (widescreen) and 4:3 (standard). Default <code>true</code></td></tr><tr><td>toggleRaiseHand</td><td><code>(enabled?: boolean) => void</code></td><td>Toggle raising and lowering your hand in the meeting. Any host in the meeting can acknowledge your request with the <code>askToSpeak</code> host action.</td></tr><tr><td>acceptWaitingParticipant</td><td><code>(participantId: string) => void</code></td><td>Accept waiting participant</td></tr><tr><td>rejectWaitingParticipant</td><td><code>(participantId: string, response?: string) => void</code></td><td>Reject waiting participant, optionally with a message.</td></tr><tr><td>startScreenshare</td><td><code>() => void</code></td><td>Start local screen share</td></tr><tr><td>stopScreenshare</td><td><code>() => void</code></td><td>Stop local screen share</td></tr><tr><td>leaveRoom</td><td><code>() => void</code></td><td>Leave the room</td></tr><tr><td>joinBreakoutGroup</td><td><code>(group: string) ⇒ void</code></td><td>Join a breakout group.</td></tr><tr><td>joinBreakoutMainRoom</td><td><code>() ⇒ void</code></td><td>Join the main room in a breakout session.</td></tr><tr><td>switchCameraEffect</td><td><code>(effectId: string) => void</code></td><td>Enable a camera effect. Use <code>getUsableCameraEffectPresets()</code> to get a valid <code>effectId</code>.</td></tr><tr><td>switchCameraEffectCustom</td><td><code>(imageUrl: string) => Promise&#x3C;void></code></td><td>Enable a camera effect that uses a custom image (from the given URL) as the background.</td></tr><tr><td>clearCameraEffect</td><td><code>() ⇒ void</code></td><td>Disable a camera effect.</td></tr><tr><td>enableAudioDenoiser</td><td><code>() ⇒ void</code></td><td>Enable noise suppression on the local microphone stream. Automatically re-applied if the microphone device is later switched. Use <code>isAudioDenoiserSupported()</code> to check browser support first.</td></tr><tr><td>disableAudioDenoiser</td><td><code>() ⇒ void</code></td><td>Disable noise suppression on the local microphone stream.</td></tr><tr><td>startLiveCaptions</td><td><code>() ⇒ void</code></td><td>Start live captions for local participant only (if configured)</td></tr><tr><td>stopLiveCaptions</td><td><code>() ⇒ void</code></td><td>Stop live captions for local participant only (if configured)</td></tr><tr><td>cancelKnock</td><td><code>() => void</code></td><td>Withdraw a pending knock and leave the waiting room</td></tr><tr><td>holdWaitingParticipant</td><td><code>(participantId: string, response?: string) => void</code></td><td>Put a waiting participant on hold, optionally with a message explaining why (for example "We're running 5 minutes late").<br><br>The participant stays in the waiting room and in your <code>waitingParticipants</code> list, so you can still accept or reject them later. Their connection status changes to <code>knock_on_hold</code> and the message is delivered in <code>knockResponse</code>. See <a href="https://docs.whereby.com/whereby-for-web-browser/react-based-browser-sdk/waiting-room-messages">Waiting room messages</a>.</td></tr></tbody></table>

#### Host-only actions

When a participant provides a valid "host" `roomKey` in the [`RoomConnectionOptions`](/reference/react-hooks-reference/types.md#roomconnectionoptions) when the [useRoomConnection](/reference/react-hooks-reference/useroomconnection.md) hook was created, they will have access to a number of addition host-only actions in rooms:

<table><thead><tr><th width="239.33333333333331">Property</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>lockRoom</td><td><code>(locked: boolean) => void</code></td><td><strong>[Host only]</strong> Lock (<code>true</code>) or unlock (<code>false</code>) the current room</td></tr><tr><td>muteParticipants</td><td><code>(participantIds: string[]) => void</code></td><td><strong>[Host only]</strong> Mute the specified remote participants</td></tr><tr><td>askToSpeak</td><td><code>(participantId: string) => void</code></td><td><p><strong>[Host only]</strong> Ask the specified remote participant to unmute their microphone and speak in the meeting.</p><p>This is typically useful in response to a <code>toggleRaiseHand</code> request from a participant in the meeting.</p></td></tr><tr><td>askToTurnOnScreenshare</td><td><code>(participantId: string) => void</code></td><td><strong>[Host only]</strong> Ask the specified remote participant to start screen sharing.</td></tr><tr><td>kickParticipant</td><td><code>(participantId: string) => void</code></td><td><strong>[Host only]</strong> Remove the specified remote participant from the meeting</td></tr><tr><td>endMeeting</td><td><code>(stayBehind?: boolean) => void</code></td><td><p><strong>[Host only]</strong> End the meeting for <em>all</em> remote participants.</p><p>If <code>stayBehind</code> is not provided or is not <code>true</code>, then the local participant will also leave the room</p></td></tr><tr><td>spotlightParticipant</td><td><code>(participantId: string) => void</code></td><td><strong>[Host only]</strong> Put a spotlight on a participant.<br><br>When used in combination with the video grid, the spotlighted participant will move to the presentation stage, and their video cell will be bigger.</td></tr><tr><td>removeSpotlight</td><td><code>(participantId: string) => void</code></td><td><strong>[Host only]</strong> Remove spotlight on a participant.</td></tr><tr><td>stopParticipantScreenshare</td><td><code>(participantId: string) => void</code></td><td><strong>[Host only]</strong> Forcefully stop remote participants screen share (if they are currently sharing their screen in the meeting)</td></tr><tr><td>startCloudRecording</td><td><code>() ⇒ void</code></td><td><strong>[Host only]</strong> Start cloud recording (if configured)</td></tr><tr><td>stopCloudRecording</td><td><code>() ⇒ void</code></td><td><strong>[Host only]</strong> Stop cloud recording (if configured)</td></tr><tr><td>startLiveTranscription</td><td><code>() ⇒ void</code></td><td><strong>[Host only]</strong> Start live transcription (if configured)</td></tr><tr><td>stopLiveTranscription</td><td><code>() ⇒ void</code></td><td><strong>[Host only]</strong> Stop live transcription (if configured)</td></tr></tbody></table>

#### **Breakout host actions**

Hosts can start, configure and steer a breakout session with the actions below. They all require the host role *and* a group (SFU) room, check `state.breakout.isAvailable` before showing breakout controls in your UI, and read `state.breakout.error` if an action is refused. See Breakout sessions for the full flow.

| Property                        | Type                                                    | Description                                                                                                                                                                                                                                                                                                    |
| ------------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| startBreakoutSession            | `(options: StartBreakoutSessionOptions) => void`        | **\[Host only]** Start a breakout session with the given groups, optional participant assignments and session settings                                                                                                                                                                                         |
| updateBreakoutSession           | `(options: UpdateBreakoutSessionOptions) => void`       | **\[Host only]** Update the groups, assignments and/or settings. Can be called both before and during a session, only the fields you pass are changed                                                                                                                                                          |
| stopBreakoutSession             | `() => void`                                            | **\[Host only]** End the breakout session and return participants to the main room                                                                                                                                                                                                                             |
| assignBreakoutParticipants      | `(assignments: { [clientId: string]: string }) => void` | <p><strong>\[Host only]</strong> Assign participants to groups, as a map of <code>clientId → groupId</code>.<br><br>Merged with the current assignments: participants you leave out keep theirs, and an empty <code>groupId</code> unassigns a participant.</p>                                                |
| assignAllBreakoutParticipants   | `() => void`                                            | **\[Host only]** Randomly distribute all remote participants evenly across the groups                                                                                                                                                                                                                          |
| unassignAllBreakoutParticipants | `() => void`                                            | **\[Host only]** Clear every group assignment                                                                                                                                                                                                                                                                  |
| shuffleBreakoutParticipants     | `() => void`                                            | **\[Host only]** Re-distribute the already-assigned participants randomly across the groups. Participants without an assignment are left out                                                                                                                                                                   |
| extendBreakoutTimer             | `(seconds?: number) => void`                            | **\[Host only]** Give the groups more time by adding to the timer duration. Defaults to 60 seconds                                                                                                                                                                                                             |
| stopBreakoutTimer               | `() => void`                                            | **\[Host only]** Turn the timer off without ending the session — the groups keep running until you call `stopBreakoutSession`                                                                                                                                                                                  |
| broadcastToGroups               | `(participantId: string) => void`                       | <p><strong>\[Host only]</strong> Broadcast a main-room participant into every breakout group, so they can make an announcement without visiting each group.<br><br>This spotlights the participant, and participants inside a group will see them in <code>state.breakout.broadcastingParticipants</code>.</p> |
| stopBroadcastToGroups           | `(participantId: string) => void`                       | **\[Host only]** Stop broadcasting the participant into the groups (removes their spotlight)                                                                                                                                                                                                                   |

### events

Event emitter which emits notification events as they are happening inside of the room.

It's possible to subscribe and unsubscribe to events using the `events.on` and `events.off` methods.

| Event                     | Payload                                                                                                                                                                  | Description                                                                                                                                                                                                                                                                          |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| \*                        | [NotificationEvent](/reference/react-hooks-reference/types.md#notificationevent)                                                                                         | Listen for all events                                                                                                                                                                                                                                                                |
| requestAudioEnable        | [NotificationEvent](/reference/react-hooks-reference/types.md#notificationevent)<[RequestAudioEvent](/reference/react-hooks-reference/types.md#requestaudioevent)>       | <p>A host is asking for the local participant to speak in the meeting.</p><p>The local participant should be notified when this event is received and prompted to trigger <code>actions.toggleMicrophone(true)</code> if or when they are ready to speak</p>                         |
| requestAudioDisable       | [NotificationEvent](/reference/react-hooks-reference/types.md#notificationevent)<[RequestAudioEvent](/reference/react-hooks-reference/types.md#requestaudioevent)>       | A host has forcibly muted your microphone                                                                                                                                                                                                                                            |
| requestScreenshareEnable  | [NotificationEvent](/reference/react-hooks-reference/types.md#notificationevent)<[RequestScreenshareEvent](/reference/react-hooks-reference/types.md#requestaudioevent)> | <p>A host is asking for the local participant to share their screen in the meeting.</p><p>The local participant should be notified when this event is received and prompted to trigger <code>actions.startScreenshare()</code> if or when they are ready to start screen sharing</p> |
| requestScreenshareDisable | [NotificationEvent](/reference/react-hooks-reference/types.md#notificationevent)<[RequestScreenshareEvent](/reference/react-hooks-reference/types.md#requestaudioevent)> | A host has forcibly stopped your screen share                                                                                                                                                                                                                                        |
| signalTrouble             | [NotificationEvent](/reference/react-hooks-reference/types.md#notificationevent)<[SignalStatusEvent](/reference/react-hooks-reference/types.md#signalstatusevent)>       | There is a problem with the internet connection and a connection to our signal server can not be established                                                                                                                                                                         |
| signalOk                  | [NotificationEvent](/reference/react-hooks-reference/types.md#notificationevent)<[SignalStatusEvent](/reference/react-hooks-reference/types.md#signalstatusevent)>       | Internet connectivity is present or it has been restored after `signalTrouble`                                                                                                                                                                                                       |
| chatMessageReceived       | [NotificationEvent](/reference/react-hooks-reference/types.md#notificationevent)<[ChatMessageEvent](/reference/react-hooks-reference/types.md#chatmessageevent)>         | A chat message was sent by a remote participant                                                                                                                                                                                                                                      |

#### **Breakout events**

Emitted to every participant in a room with an active breakout session.

| Event                 | Payload                                         | Description                                                                                                                                                                   |
| --------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| breakoutGroupAssigned | `NotificationEvent<BreakoutGroupAssignedEvent>` | The local participant was assigned to a breakout group. Use this to prompt them to join, or to explain an imminent automatic move. Being *un*assigned does not emit an event. |
| breakoutTimerEnding   | `NotificationEvent<BreakoutTimerEvent>`         | The breakout timer is about to run out. A good moment to warn the groups that they'll be sent back to the main room shortly                                                   |
| breakoutTimerEnded    | `NotificationEvent<BreakoutTimerEvent>`         | The breakout timer ran out                                                                                                                                                    |
| breakoutTimerExtended | `NotificationEvent<BreakoutTimerEvent>`         | A host added time to the running breakout timer                                                                                                                               |

#### Host-only events

When a participant provides a valid "host" `roomKey` in the [`RoomConnectionOptions`](/reference/react-hooks-reference/types.md#roomconnectionoptions) when the [useRoomConnection](/reference/react-hooks-reference/useroomconnection.md) hook was created, they will have access to a number of addition host-only events in rooms:

| Event             | Payload                                                                                                                                                                | Description                                                                                                                                                                                                                                                                                                                 |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| remoteHandRaised  | [NotificationEvent](/reference/react-hooks-reference/types.md#notificationevent)<[StickyReactionEvent](/reference/react-hooks-reference/types.md#stickyreactionevent)> | <p>A remote participant has raised their hand to request to speak in the meeting.</p><p>The local host participant should be notified when this event is received and prompted to trigger <code>actions.askToSpeak(participantId)</code> if or when they want to invite the remote participant to speak in the meeting.</p> |
| remoteHandLowered | [NotificationEvent](/reference/react-hooks-reference/types.md#notificationevent)<[StickyReactionEvent](/reference/react-hooks-reference/types.md#stickyreactionevent)> | <p>A remote participant who previously had their hand raised has now lowered their hand.</p><p>Any previous raised hand notifications shown for this remote participant should be cancelled and no further action is needed from the local host participant.</p>                                                            |

## Usage

```tsx
import * as React from "react";
import { useRoomConnection, VideoView } from "@whereby.com/browser-sdk/react";

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

    const { connectionState, remoteParticipants } = state;
    const { joinRoom, leaveRoom, toggleCamera, toggleMicrophone } = actions;
    
    React.useEffect(() => {
        joinRoom().catch(error => console.error("Could not join room", error));
        return () => leaveRoom();
    }, []);

    // listen to all notification events on mount and unlisten on unmount
    React.useEffect(() => {
        if(!events) return;
        const handleEvents = (e) => console.log(e);
        events.on("*", handleEvents);
        return () => events && events.off("*", handleEvents);
    }, []);

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

[^1]: Only needed when the roomConnectionStatus is `room_locked`