usePresence for PubNub Chat Components for React

Migrate to Chat SDK

PubNub will stop supporting Chat Components on January 1, 2025 but you are welcome to contribute. Learn how to migrate to the Chat SDK here.

The hook returns the list of unique user IDs currently subscribed to the channel.

This hook also sets up a listener that reacts to new presence events (joins and leaves/timeouts). However, this behavior requires a living subscription to the channels passed to the hook - this should be handled by the components.

Information returned by this hook can be used to show a presence indicator, or a number of people currently subscribed to the channel.

const [channels, refetchPresence, totalPresence, error, isLoading] = usePresence({
  channels: ["test-channel"],
});

return <p>Occupancy of the channel: {channels["test-channel"].occupancy}</p>;

Input

User ID / UUID

User ID is also referred to as UUID/uuid in some APIs and server responses but holds the value of the userId parameter you set during initialization.

Parameter	Type	Required	Defaults	Description
channels	Array	Optional	n/a	Channel name to return occupancy results. If channel is not provided, hereNow() will return data for all channels.
channelGroups	Array	Optional	n/a	Channel group for which hereNow() information should be received.
includeUUIDs	Boolean	Optional	true	Option to disable returning User IDs.
includeState	Boolean	Optional	false	Option to enable returning subscriber state information.

Output

Parameter	Type	Description
array[0]	ChannelPresence[]	List of returned channel presence data.
array[1]	Function	Refetching presence from scratch. This is rarely needed since the hook sets up presence listeners to get updates.
array[2]	Number	Total number of present users across all passed channels.
array[3]	Error	If there's an error fetching presence, it will be available here.
array[4]	Boolean	Indicator that the channel presence data is still being loaded.

ChannelPresence interface

  [channel: string]: {
    name: string;
    occupancy: number;
    occupants?: {
      uuid: string;
      state?: unknown;
    }[];
  };