> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-v6-beta2-flutter-uikit.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# User Presence

> Track real-time online/offline status of users in your React Native app using CometChat SDK presence subscriptions and user listeners.

<Info>
  **Quick Reference** - Listen for user presence changes:

  ```javascript theme={null}
  CometChat.addUserListener("LISTENER_ID", new CometChat.UserListener({
    onUserOnline: (user) => console.log("Online:", user),
    onUserOffline: (user) => console.log("Offline:", user),
  }));

  // Cleanup
  CometChat.removeUserListener("LISTENER_ID");
  ```
</Info>

<Note>
  **Available via:** [SDK](/sdk/react-native/user-presence) | [UI Kits](/ui-kit/react-native/users)
</Note>

User Presence helps us understand if a user is available to chat or not.

## Real-time Presence

*In other words, as a logged-in user, how do I know if a user is online or offline?*

Based on the settings provided in the AppSettings class while initialising the SDK using the `init()` method, the logged-in user will receive the presence for the other users in the app.

In the `AppSettings` class, you can set the type of Presence you wish to receive for that particular session of the app.

For presence subscription, the AppSettingsBuilder provides 3 methods :

* `subscribePresenceForAllUsers()` - this will inform the logged-in user when any user in the app comes online or goes offline
* `subscribePresenceForRoles(Array roles)` - This will inform the logged-in user, only when the users with the specified roles come online or go offline.
* `subscribePresenceForFriends()` - This will inform the logged-in user, only when either of his friends come online or go offline.

If none of the above methods are used, no presence will be sent to the logged-in user.

You need to register the `UserListener` using the `addUserListener()` method where ever you wish to receive these events in.

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    let listenerID = "UNIQUE_LISTENER_ID";

    CometChat.addUserListener(
    listenerID,
    new CometChat.UserListener({
      onUserOnline: onlineUser => {
        console.log("On User Online:", { onlineUser });
      },
      onUserOffline: offlineUser => {
        console.log("On User Offline:", { offlineUser });
      }
    })
    );
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    let listenerID: string = "UNIQUE_LISTENER_ID";

    CometChat.addUserListener(
      listenerID,
      new CometChat.UserListener({
          onUserOnline: (onlineUser: CometChat.User) => {
              console.log("On User Online:", { onlineUser });
          },
          onUserOffline: (offlineUser: CometChat.User) => {
              console.log("On User Offline:", { offlineUser });
          }
      })
    );
    ```
  </Tab>
</Tabs>

<Accordion title="onUserOnline Response">
  **On Event** — `onUserOnline` returns a `User` object when a user comes online:

  | Parameter       | Type    | Description                                       | Sample Value                                        |
  | --------------- | ------- | ------------------------------------------------- | --------------------------------------------------- |
  | `uid`           | string  | Unique identifier of the user                     | `"cometchat-uid-7"`                                 |
  | `name`          | string  | Display name of the user                          | `"Henry Marino"`                                    |
  | `avatar`        | string  | URL to user's avatar image                        | `"https://artriva.com/media/k2/galleries/20/d.jpg"` |
  | `status`        | string  | User's online status                              | `"online"`                                          |
  | `role`          | string  | User's role                                       | `"default"`                                         |
  | `lastActiveAt`  | number  | Unix timestamp of last activity                   | `1772174142305`                                     |
  | `hasBlockedMe`  | boolean | Whether this user has blocked the current user    | `false`                                             |
  | `blockedByMe`   | boolean | Whether the current user has blocked this user    | `false`                                             |
  | `deactivatedAt` | number  | Timestamp when user was deactivated (0 if active) | `0`                                                 |
</Accordion>

<Accordion title="onUserOffline Response">
  **On Event** — `onUserOffline` returns a `User` object when a user goes offline:

  | Parameter       | Type    | Description                                       | Sample Value                                        |
  | --------------- | ------- | ------------------------------------------------- | --------------------------------------------------- |
  | `uid`           | string  | Unique identifier of the user                     | `"cometchat-uid-7"`                                 |
  | `name`          | string  | Display name of the user                          | `"Henry Marino"`                                    |
  | `avatar`        | string  | URL to user's avatar image                        | `"https://artriva.com/media/k2/galleries/20/d.jpg"` |
  | `status`        | string  | User's online status                              | `"offline"`                                         |
  | `role`          | string  | User's role                                       | `"default"`                                         |
  | `lastActiveAt`  | number  | Unix timestamp of last activity                   | `1772174136215`                                     |
  | `hasBlockedMe`  | boolean | Whether this user has blocked the current user    | `false`                                             |
  | `blockedByMe`   | boolean | Whether the current user has blocked this user    | `false`                                             |
  | `deactivatedAt` | number  | Timestamp when user was deactivated (0 if active) | `0`                                                 |
</Accordion>

| Parameter    | Description                                   |
| ------------ | --------------------------------------------- |
| `listenerID` | An ID that uniquely identifies that listener. |

You will receive an object of the `User` class in the listener methods.

<Note>
  Presence events are triggered for other users, not for yourself. For example, if User 1 is logged in and User 2 comes online, User 1 receives `onUserOnline` for User 2. Neither User 1 nor User 2 receive presence events for their own status changes — only for others.
</Note>

<Warning>
  Always remove user listeners when the component unmounts using `CometChat.removeUserListener(listenerID)`. Failing to remove listeners can cause memory leaks and duplicate event handling.
</Warning>

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    let listenerID = "UNIQUE_LISTENER_ID";
    CometChat.removeUserListener(listenerID);
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    let listenerID: string = "UNIQUE_LISTENER_ID";
    CometChat.removeUserListener(listenerID); 
    ```
  </Tab>
</Tabs>

## User List Presence

*In other words, as a logged-in user, when I retrieve the user list, how do I know if a user is online/offline?*

When you fetch the list of users, in the [User](/sdk/react-native/user-management#user-class) object, you will receive 2 fields

1. `status` - This will hold either of the two values :

* online - This indicates that the user is currently online and available to chat.
* offline - This indicates that the user is currently offline and is not available to chat.

2. `lastActiveAt` - in case the user is offline, this field holds the timestamp of the time when the user was last online. This can be used to display the Last seen of the user if need be.

## Best Practices

<AccordionGroup>
  <Accordion title="Choose the right presence subscription">
    Use `subscribePresenceForAllUsers()` only if your app needs to track all users. For most apps, `subscribePresenceForFriends()` or `subscribePresenceForRoles()` is more efficient and reduces unnecessary network traffic.
  </Accordion>

  <Accordion title="Set presence subscription during init">
    Presence subscription is configured in `AppSettings` during SDK initialization. You cannot change the subscription type without re-initializing the SDK. Plan your subscription strategy before calling `init()`.
  </Accordion>

  <Accordion title="Use lastActiveAt for 'Last seen' display">
    When a user is offline, use the `lastActiveAt` timestamp to show "Last seen X minutes ago" in your UI. This gives users context about when the person was last available.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Presence events not received">
    Verify that you configured a presence subscription method (`subscribePresenceForAllUsers`, `subscribePresenceForRoles`, or `subscribePresenceForFriends`) in your `AppSettings` during `init()`. Without this, no presence events are delivered.
  </Accordion>

  <Accordion title="onUserOnline fires but onUserOffline doesn't">
    Offline events are triggered when the SDK detects the user has disconnected. This may have a short delay depending on network conditions. The event will fire once the server confirms the user is offline.
  </Accordion>

  <Accordion title="Presence not updating for specific users">
    If using `subscribePresenceForRoles()`, ensure the target users have the specified roles assigned. If using `subscribePresenceForFriends()`, confirm the users are in each other's friends list.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Retrieve Users" icon="users" href="/sdk/react-native/retrieve-users">
    Fetch user lists with online/offline status
  </Card>

  <Card title="User Management" icon="user-plus" href="/sdk/react-native/user-management">
    Create, update, and delete users in CometChat
  </Card>

  <Card title="Block Users" icon="ban" href="/sdk/react-native/block-users">
    Block and unblock users, retrieve blocked user lists
  </Card>

  <Card title="SDK Setup" icon="wrench" href="/sdk/react-native/setup-sdk">
    Configure AppSettings including presence subscriptions
  </Card>
</CardGroup>