usePresence

Open in

The usePresence hook manages the current user's presence in a chat room. By default, it automatically enters presence on mount and leaves on unmount. Use usePresenceListener to observe the presence state of all users.

React

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

const MyComponent = () => {
  const { update, myPresenceState } = usePresence();

  return (
    <div>
      <p>Present: {myPresenceState.present ? 'Yes' : 'No'}</p>
      <button onClick={() => update({ status: 'away' })}>Set Away</button>
    </div>
  );
};

This hook must be used within a ChatRoomProvider.

Parameters

The usePresence hook accepts an optional configuration object:

autoEnterLeaveoptionalBoolean

Whether the hook should automatically enter presence on mount and leave on unmount. If leave() is invoked, automatic entry is disabled until enter or update is called. Default: true.

initialDataoptionalPresenceData

Data to use when auto-entering the room. Only applies to the initial auto-enter on component mount; subsequent modifications are disregarded. Use update or enter for post-entry data changes.

onDiscontinuityoptionalDiscontinuityListener

A callback to detect and respond to discontinuities.

onRoomStatusChangeoptionalRoomStatusChange

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 usePresence hook returns an object with the following properties:

enterenter()

Enters the current user into the presence set.

leaveleave()

Removes the current user from the presence set.

updateupdate()

Updates the current user's presence data.

myPresenceStateMyPresenceState

The current presence state of the user, including whether they are present and any errors.

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.

Enter presence

enter(data?: PresenceData): Promise<void>

Enters the current user into the chat room presence set. This notifies other users that you have joined the room.

Parameters

dataoptionalPresenceData

JSON-serializable data to associate with the user's presence.

Returns

Promise<void>

Returns a promise. The promise is fulfilled when the user has successfully entered the presence set, or rejected with an ErrorInfo object.

Update presence data

update(data?: PresenceData): Promise<void>

Updates the presence data for the current user in the chat room. Use this to change your status or other presence information without leaving and re-entering. Automatically enters if not already present.

Parameters

dataoptionalPresenceData

JSON-serializable data to replace the user's current presence data.

Returns

Promise<void>

Returns a promise. The promise is fulfilled when the presence data has been updated, or rejected with an ErrorInfo object.

Leave presence

leave(data?: PresenceData): Promise<void>

Removes the current user from the chat room presence set. This notifies other users that you have left the room. If autoEnterLeave is true, calling leave() prevents automatic re-entry until enter or update is called.

Parameters

dataoptionalPresenceData

Final presence data to include with the leave event.

Returns

Promise<void>

Returns a promise. The promise is fulfilled when the user has left the presence set, or rejected with an ErrorInfo object.

Example

React

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

function PresenceControls() {
  const { enter, leave, update, myPresenceState } = usePresence({
    initialData: { status: 'online', nickname: 'Alice' },
  });

  return (
    <div>
      <p>Status: {myPresenceState.present ? 'Online' : 'Offline'}</p>
      {myPresenceState.error && <p>Error: {myPresenceState.error.message}</p>}
      <button onClick={() => update({ status: 'away' })}>Set Away</button>
      <button onClick={() => leave()}>Leave</button>
      <button onClick={() => enter({ status: 'online' })}>Rejoin</button>
    </div>
  );
}