Optionalparams: UsePresenceParamsOptional parameters for initial data, auto-enter/leave behavior, and status callbacks
A UsePresenceResponse containing presence methods and current state
// Example with full manual control (no auto-enter/leave)
const ManualPresenceComponent = () => {
const { enter, leave, update, myPresenceState } = usePresence({
autoEnterLeave: false,
initialData: { status: 'available' }
});
const handleJoin = () => enter({ status: 'online' });
const handleLeave = () => leave();
const handleUpdateStatus = () => update({ status: 'busy' });
return (
<div>
<button onClick={handleJoin}>Join</button>
<button onClick={handleLeave}>Leave</button>
<button onClick={handleUpdateStatus}>Update Status</button>
<div>Present: {myPresenceState.present}</div>
</div>
);
};
// Example with auto-enter but taking manual control via leave.
// This pattern is useful if you have multiple components in your app updating presence data.
const MixedControlComponent = () => {
const { leave, update, myPresenceState } = usePresence({
initialData: { status: 'online' }
});
const handleGoOffline = () => {
// Calling leave() prevents auto re-entry until enter() or update() is called
leave({ status: 'offline' });
};
const handleUpdatePresence = () => {
// Calling update() re-enables auto-enter behavior
update({ status: 'back online' });
};
return (
<div>
<button onClick={handleGoOffline}>Go Offline</button>
<button onClick={handleUpdatePresence}>Update Presence</button>
<div>Present: {myPresenceState.present}</div>
</div>
);
};
// Example with manual mount/unmount behavior using enter/leave explicitly
const ManualMountComponent = () => {
const { enter, leave, myPresenceState } = usePresence({
autoEnterLeave: false,
initialData: { status: 'ready' }
});
// Manual mount behavior - enter presence when component mounts
useEffect(() => {
enter({ status: 'active' });
// Manual unmount behavior - leave presence when component unmounts
return () => {
leave({ status: 'disconnecting' });
};
}, [enter, leave]);
return <div>Present: {myPresenceState.present}</div>;
};
React hook that manages user presence in a chat room.
This hook provides comprehensive presence functionality with both automatic and manual control modes. It handles entering/leaving presence, updating presence data, and tracking the current presence state with automatic recovery after disconnections.
By default (
autoEnterLeave: true), the hook automatically enters presence when the component mounts and the room is attached, and leaves when unmounting. It also handles automatic re-entry after room detachment/reattachment cycles.With
autoEnterLeave: false, you have full manual control over presence lifecycle using the returnedenterandleavemethods.Important: When using
autoEnterLeave, avoid multiple instances of this hook within the same ChatClientProvider, as they share the same underlying presence instance. For multiple components updating presence data, either:autoEnterLeave: falseand manage state manuallyNote: This hook must be used within a ChatRoomProvider component tree. Note: Room must be attached and connection active for presence operations, typically the ChatRoomProvider handles this automatically.