AblyDocs

useRoom

Open in

The useRoom hook provides access to room information and basic room operations such as manually attaching and detaching.

React

1

2

3

4

5

6

import { useRoom } from '@ably/chat/react';

const MyComponent = () => {
  const { roomName, roomStatus } = useRoom();
  return <p>Room: {roomName} ({roomStatus})</p>;
};

This hook must be used within a ChatRoomProvider.

Parameters

The useRoom hook accepts an optional configuration object:

onStatusChangeoptionalRoomStatusChange
A callback invoked when the room status changes. Removed when the component unmounts.
onConnectionStatusChangeoptionalConnectionStatusChange
A callback invoked when the connection status changes. Removed when the component unmounts.

Returns

The useRoom hook returns an object with the following properties:

roomNameString
The unique identifier of the room.
roomStatusRoomStatus
The current status of the room, kept up to date by the hook.
roomErrorErrorInfo or Undefined
An error object if the room is in an errored state.
connectionStatusConnectionStatus
The current connection status, kept up to date by the hook.
connectionErrorErrorInfo or Undefined
An error object if there is a connection error.
attachattach()
Manually attach to the room.
detachdetach()
Manually detach from the room.

Attach to a room

attach(): Promise<void>

Attach to the room to start receiving messages and events. The ChatRoomProvider handles this automatically; this method is only needed for manual lifecycle control.

Returns

Promise<void>

Returns a promise. The promise is fulfilled when the room is attached, or rejected with an ErrorInfo object.

Detach from a room

detach(): Promise<void>

Detach from the room to stop receiving messages and events. Existing subscriptions are preserved but will not receive events until the room is re-attached. The ChatRoomProvider handles this automatically; this method is only needed for manual lifecycle control.

Returns

Promise<void>

Returns a promise. The promise is fulfilled when the room is detached, or rejected with an ErrorInfo object.

RoomStatus

The status of a chat room.

Initializing
The library is currently initializing the room. This is a temporary state used in React prior to the room being resolved. The value is initializing.
Initialized
The room has been initialized, but no attach has been attempted yet. The value is initialized.
Attaching
An attach has been initiated by sending a request to Ably. This is a transient status and will be followed by a transition to Attached, Suspended, or Failed. The value is attaching.
Attached
The room is attached and actively receiving events. In this status, clients can publish and subscribe to messages, and enter the presence set. The value is attached.
Detaching
A detach has been initiated on the attached room by sending a request to Ably. This is a transient status and will be followed by a transition to Detached or Failed. The value is detaching.
Detached
The room has been detached by the client and is no longer receiving events. The value is detached.
Suspended
The room, having previously been attached, has lost continuity. This typically occurs when the client is disconnected from Ably for more than two minutes. The client will automatically attempt to reattach when connectivity is restored. The value is suspended.
Failed
An indefinite failure condition. This status is entered if an error is received from Ably, such as an attempt to attach without the necessary access rights. The value is failed.
Releasing
The room is being released and its resources are being cleaned up. Attempting to use a room in this state may result in undefined behavior. The value is releasing.
Released
The room has been released and is no longer usable. A new room instance must be obtained to continue using the room. The value is released.

RoomStatusChange

Describes a change in room status.

currentRoomStatus
The new status of the room.
previousRoomStatus
The previous status of the room.
errorErrorInfo or Undefined
An error that provides a reason why the room has entered the new status, if applicable.

Example

React

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

import { RoomStatus } from '@ably/chat';
import { useRoom } from '@ably/chat/react';

function RoomHeader() {
  const { roomName, roomStatus, roomError } = useRoom({
    onStatusChange: (change) => {
      console.log(`Room status: ${change.previous} -> ${change.current}`);
    },
  });

  return (
    <header>
      <h2>{roomName}</h2>
      <span>{roomStatus}</span>
      {roomStatus === RoomStatus.Failed && roomError && (
        <p>Error: {roomError.message}</p>
      )}
    </header>
  );
}