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.

* required

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

Output

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

ChannelPresence interface

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