Function usePresenceListener

usePresenceListener(
params?: UsePresenceListenerParams,
): UsePresenceListenerResponse

React hook that provides real-time presence data for all users in a room.

This hook automatically subscribes to presence events and maintains an up-to-date list of all presence members in the room.

Note:

This hook must be used within a ChatRoomProvider component tree.
Room must be attached to receive presence updates, typically the ChatRoomProvider handles this automatically.

Parameters

Optionalparams: UsePresenceListenerParams
Optional parameters for event listeners and room status callbacks

Returns UsePresenceListenerResponse

A UsePresenceListenerResponse containing current presence data and error state

Throws

An Ably.ErrorInfo with ReactHookMustBeUsedWithinProvider When used outside of a ChatRoomProvider

Example: Basic usage

import React from 'react';
import { ChatClient, PresenceEvent } from '@ably/chat';
import {
  ChatClientProvider,
  ChatRoomProvider,
  usePresenceListener
} from '@ably/chat/react';

// Component that displays all presence members
const PresenceList = () => {
  const { presenceData, error } = usePresenceListener({
    listener: (presenceEvent: PresenceEvent) => {
      console.log(`Presence ${presenceEvent.type}:`, presenceEvent.member);
    },
  });

  if (error) {
    return <div>Error: {error.message}</div>;
  }

  return (
    <div>
      <p>Total Members: {presenceData.length}</p>
      <ul>
        {presenceData.map((member) => (
          <li key={member.clientId}>👤 {member.clientId}</li>
        ))}
      </ul>
    </div>
  );
};

const chatClient: ChatClient; // existing ChatClient instance

// App component with providers
const App = () => {
  return (
    <ChatClientProvider client={chatClient}>
      <ChatRoomProvider name="team-room">
        <PresenceList />
      </ChatRoomProvider>
    </ChatClientProvider>
  );
};

export default App;