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

# Conversations

> Display CometChat React Native UI Kit conversations with last messages, unread counts, typing indicators, presence, and callbacks.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatConversations",
    "package": "@cometchat/chat-uikit-react-native",
    "import": "import { CometChatConversations } from \"@cometchat/chat-uikit-react-native\";",
    "description": "Scrollable list of recent one-on-one and group conversations for the logged-in user.",
    "primaryOutput": {
      "prop": "onItemPress",
      "type": "(conversation: CometChat.Conversation) => void"
    },
    "props": {
      "data": {
        "conversationsRequestBuilder": {
          "type": "CometChat.ConversationsRequestBuilder",
          "default": "SDK default (30 per page)",
          "note": "Pass the builder, not the result of .build()"
        },
        "datePattern": {
          "type": "(conversation: CometChat.Conversation) => string",
          "note": "Custom function to format conversation timestamps"
        }
      },
      "callbacks": {
        "onItemPress": "(conversation: CometChat.Conversation) => void",
        "onItemLongPress": "(conversation: CometChat.Conversation) => void",
        "onBack": "() => void",
        "onSelection": "(conversations: Array<CometChat.Conversation>) => void",
        "onError": "(error: CometChat.CometChatException) => void",
        "onEmpty": "() => void",
        "onLoad": "(list: CometChat.Conversation[]) => void",
        "onSearchBarClicked": "() => void",
        "onSearchTextChanged": "(searchText: string) => void",
        "onSubmit": "(conversations: Array<CometChat.Conversation>) => void"
      },
      "visibility": {
        "hideBackButton": { "type": "boolean", "default": true },
        "hideHeader": { "type": "boolean", "default": false },
        "hideError": { "type": "boolean", "default": false },
        "receiptsVisibility": { "type": "boolean", "default": true },
        "hideSubmitButton": { "type": "boolean", "default": true },
        "usersStatusVisibility": { "type": "boolean", "default": true },
        "groupTypeVisibility": { "type": "boolean", "default": true },
        "deleteConversationOptionVisibility": { "type": "boolean", "default": true },
        "showSearchBar": { "type": "boolean", "default": false },
        "searchText": { "type": "string", "default": "\"\"" }
      },
      "sound": {
        "disableSoundForMessages": { "type": "boolean", "default": false },
        "customSoundForMessages": { "type": "audio source", "default": "built-in" }
      },
      "selection": {
        "selectionMode": {
          "type": "SelectionMode",
          "values": ["single", "multiple", "none"],
          "default": "none"
        }
      },
      "viewSlots": {
        "ItemView": "(conversation: CometChat.Conversation) => JSX.Element",
        "LeadingView": "(conversation: CometChat.Conversation) => JSX.Element",
        "TitleView": "(conversation: CometChat.Conversation) => JSX.Element",
        "SubtitleView": "(conversation: CometChat.Conversation) => JSX.Element",
        "TrailingView": "(conversation: CometChat.Conversation) => JSX.Element",
        "LoadingView": "() => JSX.Element",
        "EmptyView": "() => JSX.Element",
        "ErrorView": "() => JSX.Element",
        "AppBarOptions": "() => JSX.Element",
        "SearchView": "() => JSX.Element"
      },
      "formatting": {
        "textFormatters": {
          "type": "CometChatTextFormatter[]",
          "default": "default formatters from data source"
        }
      }
    },
    "events": [
      {
        "name": "ccConversationDeleted",
        "payload": "CometChat.Conversation",
        "description": "Conversation deleted from list"
      }
    ],
    "sdkListeners": [
      "onTextMessageReceived",
      "onMediaMessageReceived",
      "onCustomMessageReceived",
      "onTypingStarted",
      "onTypingEnded",
      "onMessagesDelivered",
      "onMessagesRead",
      "onUserOnline",
      "onUserOffline",
      "onGroupMemberJoined",
      "onGroupMemberLeft",
      "onGroupMemberKicked",
      "onGroupMemberBanned",
      "onMemberAddedToGroup"
    ],
    "compositionExample": {
      "description": "Navigation-based conversations wired to message view",
      "components": [
        "CometChatConversations",
        "CometChatMessageHeader",
        "CometChatMessageList",
        "CometChatMessageComposer"
      ],
      "flow": "onItemPress emits CometChat.Conversation -> extract User/Group via getConversationWith() -> navigate to Messages screen with user or group prop"
    },
    "types": {
      "SelectionMode": {
        "single": "Select one conversation at a time",
        "multiple": "Select multiple conversations",
        "none": "No selection mode"
      }
    }
  }
  ```
</Accordion>

## Where It Fits

`CometChatConversations` is a sidebar list component. It renders recent conversations and emits the selected `CometChat.Conversation` via `onItemPress`. Wire it to `CometChatMessageHeader`, `CometChatMessageList`, and `CometChatMessageComposer` to build a standard chat layout.

```tsx lines theme={null}
import { useState } from "react";
import { View, Text, StyleSheet } from "react-native";
import { GestureHandlerRootView } from "react-native-gesture-handler";
import { SafeAreaProvider } from "react-native-safe-area-context";
import {
  CometChatConversations,
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
  CometChatThemeProvider,
} from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function ChatApp() {
  const [selectedUser, setSelectedUser] = useState<CometChat.User>();
  const [selectedGroup, setSelectedGroup] = useState<CometChat.Group>();

  const handleItemPress = (conversation: CometChat.Conversation) => {
    const entity = conversation.getConversationWith();
    if (entity instanceof CometChat.User) {
      setSelectedUser(entity);
      setSelectedGroup(undefined);
    } else if (entity instanceof CometChat.Group) {
      setSelectedGroup(entity);
      setSelectedUser(undefined);
    }
  };

  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <SafeAreaProvider>
        <CometChatThemeProvider>
          <View style={styles.container}>
            <View style={styles.sidebar}>
              <CometChatConversations onItemPress={handleItemPress} />
            </View>
            {selectedUser || selectedGroup ? (
              <View style={styles.chatArea}>
                <CometChatMessageHeader user={selectedUser} group={selectedGroup} />
                <CometChatMessageList user={selectedUser} group={selectedGroup} />
                <CometChatMessageComposer user={selectedUser} group={selectedGroup} />
              </View>
            ) : (
              <View style={styles.placeholder}>
                <Text>Select a conversation</Text>
              </View>
            )}
          </View>
        </CometChatThemeProvider>
      </SafeAreaProvider>
    </GestureHandlerRootView>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, flexDirection: "row" },
  sidebar: { width: 350 },
  chatArea: { flex: 1 },
  placeholder: { flex: 1, justifyContent: "center", alignItems: "center" },
});
```

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/mNTojjz_O28of40c/images/f2c77c5b-Conversation-ac41cc6650fbb941c64f389aee910dbc.png?fit=max&auto=format&n=mNTojjz_O28of40c&q=85&s=902e3c935963dec9f907348888829eab" width="1280" height="800" data-path="images/f2c77c5b-Conversation-ac41cc6650fbb941c64f389aee910dbc.png" />
</Frame>

***

## Minimal Render

```tsx lines theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react-native";

function ConversationsDemo() {
  return <CometChatConversations />;
}

export default ConversationsDemo;
```

***

## Filtering Conversations

Pass a `CometChat.ConversationsRequestBuilder` to `conversationsRequestBuilder`. Pass the builder instance — not the result of `.build()`.

```tsx lines theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function FilteredConversations() {
  return (
    <CometChatConversations
      conversationsRequestBuilder={
        new CometChat.ConversationsRequestBuilder()
          .setConversationType("user")
          .setLimit(10)
      }
    />
  );
}
```

### Filter Recipes

| Recipe                   | Code                                                                                               |
| ------------------------ | -------------------------------------------------------------------------------------------------- |
| Only user conversations  | `new CometChat.ConversationsRequestBuilder().setConversationType("user")`                          |
| Only group conversations | `new CometChat.ConversationsRequestBuilder().setConversationType("group")`                         |
| Limit to 10 per page     | `new CometChat.ConversationsRequestBuilder().setLimit(10)`                                         |
| With specific tags       | `new CometChat.ConversationsRequestBuilder().setTags(["vip"])`                                     |
| Filter by user tags      | `new CometChat.ConversationsRequestBuilder().withUserAndGroupTags(true).setUserTags(["premium"])`  |
| Filter by group tags     | `new CometChat.ConversationsRequestBuilder().withUserAndGroupTags(true).setGroupTags(["support"])` |

Default page size is 30. The component uses infinite scroll — the next page loads as the user scrolls to the bottom.

Refer to [ConversationRequestBuilder](/sdk/react-native/retrieve-conversations) for the full builder API.

***

## Actions and Events

### Callback Props

#### onItemPress

Fires when a conversation row is tapped. Primary navigation hook — set the active conversation and render the message view.

```tsx lines theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function ConversationsWithPress() {
  const handleItemPress = (conversation: CometChat.Conversation) => {
    console.log("Selected:", conversation.getConversationId());
  };

  return <CometChatConversations onItemPress={handleItemPress} />;
}
```

#### onItemLongPress

Fires when a conversation item is long-pressed, allowing additional actions like delete or select.

```tsx lines theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function ConversationsWithLongPress() {
  const handleLongPress = (conversation: CometChat.Conversation) => {
    console.log("Long pressed:", conversation.getConversationId());
  };

  return <CometChatConversations onItemLongPress={handleLongPress} />;
}
```

#### onSelection

Fires when conversations are selected/deselected in selection mode. Requires `selectionMode` to be set.

```tsx lines theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function ConversationsWithSelection() {
  const handleSelection = (conversations: Array<CometChat.Conversation>) => {
    console.log("Selected:", conversations.length);
  };

  return (
    <CometChatConversations
      selectionMode="multiple"
      onSelection={handleSelection}
    />
  );
}
```

#### onError

Fires on internal errors (network failure, auth issue, SDK exception).

```tsx lines theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function ConversationsWithErrorHandler() {
  return (
    <CometChatConversations
      onError={(error: CometChat.CometChatException) => {
        console.error("CometChatConversations error:", error);
      }}
    />
  );
}
```

#### onEmpty

Fires when the conversation list is empty.

```tsx lines theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react-native";

function ConversationsWithEmptyHandler() {
  return (
    <CometChatConversations
      onEmpty={() => console.log("No conversations")}
    />
  );
}
```

#### onLoad

Fires when the list is successfully fetched and loaded.

```tsx lines theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function ConversationsWithLoadHandler() {
  const handleLoad = (list: CometChat.Conversation[]) => {
    console.log("Conversations loaded:", list.length);
  };

  return <CometChatConversations onLoad={handleLoad} />;
}
```

### Global UI Events

`CometChatUIEventHandler` emits events subscribable from anywhere in the application. Subscribe in a `useEffect` and unsubscribe on cleanup.

| Event                   | Fires when                              | Payload                  |
| ----------------------- | --------------------------------------- | ------------------------ |
| `ccConversationDeleted` | A conversation is deleted from the list | `CometChat.Conversation` |

When to use: sync external UI with conversation state changes. For example, update an unread count badge in a tab bar when a conversation is deleted, or remove a conversation from a custom sidebar.

```tsx lines theme={null}
import { useEffect } from "react";
import { CometChatUIEventHandler } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function useConversationEvents() {
  useEffect(() => {
    const listenerId = "CONVERSATION_EVENTS_" + Date.now();
    
    CometChatUIEventHandler.addConversationListener(listenerId, {
      ccConversationDeleted: (conversation: CometChat.Conversation) => {
        console.log("Deleted:", conversation.getConversationId());
      },
    });

    return () => {
      CometChatUIEventHandler.removeConversationListener(listenerId);
    };
  }, []);
}
```

### SDK Events (Real-Time, Automatic)

The component listens to these SDK events internally. No manual attachment needed unless additional side effects are required.

| SDK Listener                                                                                                         | Internal behavior                                                          |
| -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `onTextMessageReceived` / `onMediaMessageReceived` / `onCustomMessageReceived`                                       | Moves conversation to top, updates last message preview and unread count   |
| `onTypingStarted` / `onTypingEnded`                                                                                  | Shows/hides typing indicator in the subtitle                               |
| `onMessagesDelivered` / `onMessagesRead`                                                                             | Updates receipt ticks (unless `receiptsVisibility={false}`)                |
| `onUserOnline` / `onUserOffline`                                                                                     | Updates online/offline status dot (unless `usersStatusVisibility={false}`) |
| `onGroupMemberJoined` / `onGroupMemberLeft` / `onGroupMemberKicked` / `onGroupMemberBanned` / `onMemberAddedToGroup` | Updates group conversation metadata                                        |

Automatic: new messages, typing indicators, receipts, user presence, group membership changes.

Manual: deleting a conversation via the SDK directly (not through the component's context menu) requires emitting `ccConversationDeleted` for the UI to update.

***

## Custom View Slots

Each slot replaces a section of the default UI. Slots that accept a conversation parameter receive the `CometChat.Conversation` object for that row.

| Slot            | Signature                                               | Replaces                          |
| --------------- | ------------------------------------------------------- | --------------------------------- |
| `ItemView`      | `(conversation: CometChat.Conversation) => JSX.Element` | Entire list item row              |
| `LeadingView`   | `(conversation: CometChat.Conversation) => JSX.Element` | Avatar / left section             |
| `TitleView`     | `(conversation: CometChat.Conversation) => JSX.Element` | Name / title text                 |
| `SubtitleView`  | `(conversation: CometChat.Conversation) => JSX.Element` | Last message preview              |
| `TrailingView`  | `(conversation: CometChat.Conversation) => JSX.Element` | Timestamp / badge / right section |
| `LoadingView`   | `() => JSX.Element`                                     | Loading spinner                   |
| `EmptyView`     | `() => JSX.Element`                                     | Empty state                       |
| `ErrorView`     | `() => JSX.Element`                                     | Error state                       |
| `AppBarOptions` | `() => JSX.Element`                                     | Header bar options                |
| `SearchView`    | `() => JSX.Element`                                     | Search bar                        |

### ItemView

Replace the entire list item row.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/G6Puyz_3Zlaowa9R/images/c6aa2b6b-Conversation_List_Item_View-60ff280389ca87aea84133ea03a6a620.png?fit=max&auto=format&n=G6Puyz_3Zlaowa9R&q=85&s=8c8a0165391da7345bafce4ba7f4fdba" width="1280" height="800" data-path="images/c6aa2b6b-Conversation_List_Item_View-60ff280389ca87aea84133ea03a6a620.png" />
</Frame>

```tsx lines theme={null}
import {
  CometChatConversations,
  CometChatAvatar,
  useTheme,
} from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { View, Text } from "react-native";

function CustomItemViewConversations() {
  const theme = useTheme();

  const getItemView = (conversation: CometChat.Conversation) => {
    const conversationWith = conversation.getConversationWith();
    return (
      <View
        style={{
          flexDirection: "row",
          flex: 1,
          paddingHorizontal: 16,
          paddingVertical: 12,
          alignItems: "center",
          borderWidth: 1,
          borderColor: theme.color.borderLight,
        }}>
        <CometChatAvatar
          name={conversationWith.getName()}
          image={{
            uri:
              conversationWith instanceof CometChat.User
                ? conversationWith.getAvatar()
                : conversationWith.getIcon(),
          }}
          style={{
            containerStyle: { borderRadius: 8 },
            imageStyle: { borderRadius: 8 },
          }}
        />
        <Text
          style={{
            flex: 1,
            color: theme.color.textPrimary,
            fontSize: 16,
            marginLeft: 12,
            fontWeight: "500",
          }}
          numberOfLines={1}
          ellipsizeMode="tail">
          {conversationWith.getName()}
        </Text>
      </View>
    );
  };

  return <CometChatConversations ItemView={getItemView} />;
}
```

### LeadingView

Replace the avatar / left section.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/le8ibYc8lBJsShSE/images/50dd219e-conversation_leading_view-65768f699fe3f064c14b0491f7ce0f91.png?fit=max&auto=format&n=le8ibYc8lBJsShSE&q=85&s=d7bba2e7d924eebd98fa5fbfee18701a" width="2560" height="1600" data-path="images/50dd219e-conversation_leading_view-65768f699fe3f064c14b0491f7ce0f91.png" />
</Frame>

```tsx lines theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { View, Text } from "react-native";

function LeadingViewConversations() {
  const getLeadingView = (conversation: CometChat.Conversation) => {
    const entity = conversation.getConversationWith();
    return (
      <View
        style={{
          width: 40,
          height: 40,
          borderRadius: 20,
          backgroundColor: "#6852D6",
          justifyContent: "center",
          alignItems: "center",
        }}>
        <Text style={{ color: "white", fontWeight: "bold" }}>
          {entity.getName().charAt(0)}
        </Text>
      </View>
    );
  };

  return <CometChatConversations LeadingView={getLeadingView} />;
}
```

### TrailingView

Replace the timestamp / badge / right section.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/JSRiWiPGBHsJZFCg/images/9c92115a-conversation_trailing_view-15ca261b8d20291c19b48c7f7af81976.png?fit=max&auto=format&n=JSRiWiPGBHsJZFCg&q=85&s=e18b00799b31bda3718d96045bae2676" width="2560" height="1600" data-path="images/9c92115a-conversation_trailing_view-15ca261b8d20291c19b48c7f7af81976.png" />
</Frame>

```tsx lines theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { View, Text } from "react-native";

function TrailingViewConversations() {
  const getTrailingView = (conversation: CometChat.Conversation) => {
    const unreadCount = conversation.getUnreadMessageCount();
    if (unreadCount === 0) return null;
    
    return (
      <View
        style={{
          backgroundColor: "#F76808",
          borderRadius: 10,
          paddingHorizontal: 8,
          paddingVertical: 4,
        }}>
        <Text style={{ color: "white", fontSize: 12, fontWeight: "bold" }}>
          {unreadCount}
        </Text>
      </View>
    );
  };

  return <CometChatConversations TrailingView={getTrailingView} />;
}
```

### TitleView

Replace the name / title text.

```tsx lines theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { View, Text } from "react-native";

function TitleViewConversations() {
  const getTitleView = (conversation: CometChat.Conversation) => {
    const entity = conversation.getConversationWith();
    const isUser = entity instanceof CometChat.User;
    
    return (
      <View style={{ flexDirection: "row", alignItems: "center", gap: 4 }}>
        <Text style={{ fontWeight: "bold", fontSize: 16 }}>
          {entity.getName()}
        </Text>
        {isUser && (entity as CometChat.User).getStatus() === "online" && (
          <View
            style={{
              width: 8,
              height: 8,
              borderRadius: 4,
              backgroundColor: "#09C26F",
            }}
          />
        )}
      </View>
    );
  };

  return <CometChatConversations TitleView={getTitleView} />;
}
```

### SubtitleView

Replace the last message preview text.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/_MYSdWhXnUkTkjEH/images/48bf8e47-Conversation_Subtitle_View-a52dabb66ff516b5afb85540c95ed92d.png?fit=max&auto=format&n=_MYSdWhXnUkTkjEH&q=85&s=8923f4ecd5cfdfbf10e4c7fc239dbe77" width="1280" height="800" data-path="images/48bf8e47-Conversation_Subtitle_View-a52dabb66ff516b5afb85540c95ed92d.png" />
</Frame>

```tsx lines theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { Text } from "react-native";

function SubtitleViewConversations() {
  const getSubtitleView = (conversation: CometChat.Conversation) => {
    const conversationWith = conversation.getConversationWith();
    if (conversationWith instanceof CometChat.User) {
      return (
        <Text style={{ fontSize: 12, color: "#727272" }}>
          Last Active: {new Date(conversationWith.getLastActiveAt() * 1000).toLocaleString()}
        </Text>
      );
    } else if (conversationWith instanceof CometChat.Group) {
      return (
        <Text style={{ fontSize: 12, color: "#727272" }}>
          {conversationWith.getMembersCount()} members
        </Text>
      );
    }
    return null;
  };

  return <CometChatConversations SubtitleView={getSubtitleView} />;
}
```

### AppBarOptions

Custom view for the header bar options.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/2JiXkJ8lq6PmPGlJ/images/6ca194c9-Conversation_Menu-f8faec49b81b7391b9b0291c77fe34e3.png?fit=max&auto=format&n=2JiXkJ8lq6PmPGlJ&q=85&s=b8ea69753781691e97cfd29bafa33203" width="1280" height="800" data-path="images/6ca194c9-Conversation_Menu-f8faec49b81b7391b9b0291c77fe34e3.png" />
</Frame>

```tsx lines theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react-native";
import { TouchableOpacity, Text } from "react-native";

function AppBarOptionsConversations() {
  return (
    <CometChatConversations
      AppBarOptions={() => (
        <TouchableOpacity onPress={() => console.log("Settings pressed")}>
          <Text style={{ color: "#6852D6", fontWeight: "500" }}>Settings</Text>
        </TouchableOpacity>
      )}
    />
  );
}
```

### options

Custom context menu actions for each conversation item.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/mkn0UqPQ5BXljCV1/images/9415d47d-conversation_set_option-42a75eb50360de67a9bfab69beefbda3.png?fit=max&auto=format&n=mkn0UqPQ5BXljCV1&q=85&s=cedd3a76dcfc73494e2651818ff49ef1" width="1280" height="800" data-path="images/9415d47d-conversation_set_option-42a75eb50360de67a9bfab69beefbda3.png" />
</Frame>

```tsx lines theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function OptionsConversations() {
  const getOptions = (conversation: CometChat.Conversation) => [
    {
      text: "Delete",
      onPress: () => console.log("Delete:", conversation.getConversationId()),
      textStyle: { color: "red" },
    },
    {
      text: "Mute",
      onPress: () => console.log("Mute:", conversation.getConversationId()),
    },
  ];

  return <CometChatConversations options={getOptions} />;
}
```

### addOptions

Extends the default context menu actions with additional options.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/ubfBSdV1t6rmjxeA/images/88283fe5-conversation_add_options-c0f407ccc43b5f040d9ab9147e17def0.png?fit=max&auto=format&n=ubfBSdV1t6rmjxeA&q=85&s=05aa1266da3006611bef12d50ab50e0f" width="1280" height="800" data-path="images/88283fe5-conversation_add_options-c0f407ccc43b5f040d9ab9147e17def0.png" />
</Frame>

```tsx lines theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function AddOptionsConversations() {
  const addOptions = (conversation: CometChat.Conversation) => [
    {
      text: "Archive",
      onPress: () => console.log("Archive:", conversation.getConversationId()),
    },
    {
      text: "Pin",
      onPress: () => console.log("Pin:", conversation.getConversationId()),
    },
  ];

  return <CometChatConversations addOptions={addOptions} />;
}
```

### datePattern

Custom date format for displaying timestamps.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/OOBJyP9hM0C-rAe_/images/def1212b-Conversation_Date_Pattern-62d23e137a26c9a0ee22e2c2cac64d80.png?fit=max&auto=format&n=OOBJyP9hM0C-rAe_&q=85&s=9b29edfea4eeb766057da73967dc2c74" width="1280" height="800" data-path="images/def1212b-Conversation_Date_Pattern-62d23e137a26c9a0ee22e2c2cac64d80.png" />
</Frame>

```tsx lines theme={null}
import {
  CometChatConversations,
  CometChatConversationUtils,
} from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function DatePatternConversations() {
  const generateDateString = (conversation: CometChat.Conversation) => {
    const lastMessage = CometChatConversationUtils.getLastMessage(conversation);
    const conversationWith = conversation.getConversationWith();
    const days = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
    const timeStamp = lastMessage?.updatedAt || conversationWith.createdAt;
    const date = new Date(timeStamp * 1000);
    const day = days[date.getUTCDay()];
    const hours = date.getUTCHours();
    const minutes = String(date.getUTCMinutes()).padStart(2, "0");
    return `${day}, ${hours}:${minutes}`;
  };

  return <CometChatConversations datePattern={generateDateString} />;
}
```

### textFormatters

Custom text formatters for the conversation subtitle.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/le8ibYc8lBJsShSE/images/55490fa9-mentions_conversations-1a7b847ad0af53848dc106216ac64e74.png?fit=max&auto=format&n=le8ibYc8lBJsShSE&q=85&s=60673bcb7af1e51ddf7a118ca123f387" width="1280" height="800" data-path="images/55490fa9-mentions_conversations-1a7b847ad0af53848dc106216ac64e74.png" />
</Frame>

```tsx lines theme={null}
import {
  CometChatConversations,
  CometChatTextFormatter,
  CometChatMentionsFormatter,
} from "@cometchat/chat-uikit-react-native";

function TextFormattersConversations() {
  const getTextFormatters = () => {
    const textFormatters: CometChatTextFormatter[] = [];
    const mentionsFormatter = new CometChatMentionsFormatter();
    mentionsFormatter.setMentionsStyle({
      textStyle: { color: "#D6409F" },
      selfTextStyle: { color: "#30A46C" },
    });
    textFormatters.push(mentionsFormatter);
    return textFormatters;
  };

  return <CometChatConversations textFormatters={getTextFormatters()} />;
}
```

See [CometChatMentionsFormatter](/ui-kit/react-native/mentions-formatter-guide) for mention formatting.

***

## Common Patterns

### Custom empty state with CTA

```tsx lines theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react-native";
import { View, Text, TouchableOpacity } from "react-native";

function EmptyStateConversations() {
  return (
    <CometChatConversations
      EmptyView={() => (
        <View style={{ flex: 1, justifyContent: "center", alignItems: "center", padding: 40 }}>
          <Text style={{ fontSize: 16, marginBottom: 16 }}>No conversations yet</Text>
          <TouchableOpacity
            style={{ backgroundColor: "#6852D6", paddingHorizontal: 20, paddingVertical: 10, borderRadius: 8 }}
            onPress={() => console.log("Start conversation")}>
            <Text style={{ color: "white" }}>Start a conversation</Text>
          </TouchableOpacity>
        </View>
      )}
    />
  );
}
```

### Hide all chrome — minimal list

```tsx lines theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react-native";

function MinimalConversations() {
  return (
    <CometChatConversations
      receiptsVisibility={false}
      usersStatusVisibility={false}
      groupTypeVisibility={false}
      deleteConversationOptionVisibility={false}
      hideHeader={true}
    />
  );
}
```

### Conversations with search

```tsx lines theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react-native";

function SearchableConversations() {
  return (
    <CometChatConversations
      showSearchBar={true}
      onSearchTextChanged={(text) => console.log("Search:", text)}
    />
  );
}
```

### Multi-select with submit

```tsx lines theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function MultiSelectConversations() {
  const handleSubmit = (conversations: Array<CometChat.Conversation>) => {
    console.log("Selected conversations:", conversations.length);
  };

  return (
    <CometChatConversations
      selectionMode="multiple"
      hideSubmitButton={false}
      onSubmit={handleSubmit}
    />
  );
}
```

***

## Styling

The component uses the theme system from `CometChatThemeProvider`. Pass a `style` prop to customize the appearance.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/k0f_g7UwNe_JINeP/images/433c987e-Conversation_Styling-1e5686a26eb349d5cbc40262b9b6df0e.png?fit=max&auto=format&n=k0f_g7UwNe_JINeP&q=85&s=c31e7cb303da50ab23c8c5fd4b8b974d" width="1280" height="800" data-path="images/433c987e-Conversation_Styling-1e5686a26eb349d5cbc40262b9b6df0e.png" />
</Frame>

```tsx lines theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react-native";

function StyledConversations() {
  return (
    <CometChatConversations
      style={{
        containerStyle: {
          backgroundColor: "#FAFAFA",
        },
        itemStyle: {
          avatarStyle: {
            containerStyle: {
              borderRadius: 8,
              backgroundColor: "#FBAA75",
            },
            imageStyle: {
              borderRadius: 8,
            },
          },
          badgeStyle: {
            containerStyle: {
              backgroundColor: "#F76808",
            },
          },
        },
      }}
    />
  );
}
```

### Style Properties

| Property         | Type        | Description                                                                                |
| ---------------- | ----------- | ------------------------------------------------------------------------------------------ |
| `containerStyle` | `ViewStyle` | Style for the root container                                                               |
| `headerStyle`    | `ViewStyle` | Style for the header section                                                               |
| `titleStyle`     | `TextStyle` | Style for the header title                                                                 |
| `itemStyle`      | `object`    | Style for list items (includes `avatarStyle`, `badgeStyle`, `titleStyle`, `subtitleStyle`) |
| `searchStyle`    | `object`    | Style for the search bar                                                                   |

<Note>
  **Avatar style override in Conversations:** `CometChatConversations` generates its own internal avatar style that overrides the base theme's `avatarStyle`. To customize avatar appearance specifically within the conversation list, you must set `avatarStyle` through the `itemStyle` prop on `CometChatConversations` (i.e., `style.itemStyle.avatarStyle`). Setting `avatarStyle` at the theme level via `CometChatThemeProvider` will not take effect for the conversation list.
</Note>

***

## Props

All props are optional unless noted.

### conversationsRequestBuilder

Controls which conversations load and in what order.

|         |                                         |
| ------- | --------------------------------------- |
| Type    | `CometChat.ConversationsRequestBuilder` |
| Default | SDK default (30 per page)               |

Pass the builder instance, not the result of `.build()`.

***

### customSoundForMessages

Custom sound file for incoming message notifications.

|         |                |
| ------- | -------------- |
| Type    | `audio source` |
| Default | Built-in sound |

***

### datePattern

Custom function to format conversation timestamps.

|         |                                                    |
| ------- | -------------------------------------------------- |
| Type    | `(conversation: CometChat.Conversation) => string` |
| Default | Component default                                  |

***

### deleteConversationOptionVisibility

Shows/hides the delete option in the context menu.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `true`    |

***

### disableSoundForMessages

Disables the notification sound for incoming messages.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### EmptyView

Custom component displayed when there are no conversations.

|         |                      |
| ------- | -------------------- |
| Type    | `() => JSX.Element`  |
| Default | Built-in empty state |

***

### ErrorView

Custom component displayed when an error occurs.

|         |                      |
| ------- | -------------------- |
| Type    | `() => JSX.Element`  |
| Default | Built-in error state |

***

### groupTypeVisibility

Shows/hides the group type icon (public/private/password).

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `true`    |

***

### hideBackButton

Hides the back button in the header.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `true`    |

***

### hideError

Hides the error state view.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideHeader

Hides the entire header bar.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideSubmitButton

Hides the submit button when selection mode is enabled.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `true`    |

***

### ItemView

Custom renderer for the entire list item row.

|         |                                                         |
| ------- | ------------------------------------------------------- |
| Type    | `(conversation: CometChat.Conversation) => JSX.Element` |
| Default | Built-in list item                                      |

***

### LeadingView

Custom renderer for the avatar / left section.

|         |                                                         |
| ------- | ------------------------------------------------------- |
| Type    | `(conversation: CometChat.Conversation) => JSX.Element` |
| Default | Built-in avatar                                         |

***

### LoadingView

Custom component displayed during the loading state.

|         |                            |
| ------- | -------------------------- |
| Type    | `() => JSX.Element`        |
| Default | Built-in loading indicator |

***

### onBack

Callback fired when the back button is pressed.

|         |              |
| ------- | ------------ |
| Type    | `() => void` |
| Default | `undefined`  |

***

### onEmpty

Callback fired when the conversation list is empty.

|         |              |
| ------- | ------------ |
| Type    | `() => void` |
| Default | `undefined`  |

***

### onError

Callback fired when the component encounters an error.

|         |                                                 |
| ------- | ----------------------------------------------- |
| Type    | `(error: CometChat.CometChatException) => void` |
| Default | `undefined`                                     |

***

### onItemLongPress

Callback fired when a conversation row is long-pressed.

|         |                                                  |
| ------- | ------------------------------------------------ |
| Type    | `(conversation: CometChat.Conversation) => void` |
| Default | `undefined`                                      |

***

### onItemPress

Callback fired when a conversation row is tapped.

|         |                                                  |
| ------- | ------------------------------------------------ |
| Type    | `(conversation: CometChat.Conversation) => void` |
| Default | `undefined`                                      |

***

### onLoad

Callback fired when conversations are loaded.

|         |                                            |
| ------- | ------------------------------------------ |
| Type    | `(list: CometChat.Conversation[]) => void` |
| Default | `undefined`                                |

***

### onSearchBarClicked

Callback fired when the search bar is clicked. Requires `showSearchBar={true}`.

|         |              |
| ------- | ------------ |
| Type    | `() => void` |
| Default | `undefined`  |

***

### onSearchTextChanged

Callback fired when search text changes. Requires `showSearchBar={true}`.

|         |                                |
| ------- | ------------------------------ |
| Type    | `(searchText: string) => void` |
| Default | `undefined`                    |

***

### onSelection

Callback fired when conversations are selected/deselected. Requires `selectionMode` to be set.

|         |                                                          |
| ------- | -------------------------------------------------------- |
| Type    | `(conversations: Array<CometChat.Conversation>) => void` |
| Default | `undefined`                                              |

***

### onSubmit

Callback fired when the submit button is pressed. Requires `selectionMode` to be set.

|         |                                                          |
| ------- | -------------------------------------------------------- |
| Type    | `(conversations: Array<CometChat.Conversation>) => void` |
| Default | `undefined`                                              |

***

### receiptsVisibility

Shows/hides message read/delivery receipt indicators.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `true`    |

***

### SearchView

Custom search bar component.

|         |                     |
| ------- | ------------------- |
| Type    | `() => JSX.Element` |
| Default | Built-in search bar |

***

### selectionMode

Enables single or multi-select mode on list items.

|         |                                    |
| ------- | ---------------------------------- |
| Type    | `"single" \| "multiple" \| "none"` |
| Default | `"none"`                           |

***

### searchText

Current search text value for the search bar.

|         |          |
| ------- | -------- |
| Type    | `string` |
| Default | `""`     |

***

### showSearchBar

Shows a search bar at the top of the list.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### SubtitleView

Custom renderer for the last message preview text.

|         |                                                         |
| ------- | ------------------------------------------------------- |
| Type    | `(conversation: CometChat.Conversation) => JSX.Element` |
| Default | Built-in subtitle                                       |

***

### textFormatters

Custom text formatters for the conversation subtitle.

|         |                                     |
| ------- | ----------------------------------- |
| Type    | `CometChatTextFormatter[]`          |
| Default | Default formatters from data source |

***

### TitleView

Custom renderer for the name / title text.

|         |                                                         |
| ------- | ------------------------------------------------------- |
| Type    | `(conversation: CometChat.Conversation) => JSX.Element` |
| Default | Built-in title                                          |

***

### TrailingView

Custom renderer for the timestamp / badge / right section.

|         |                                                         |
| ------- | ------------------------------------------------------- |
| Type    | `(conversation: CometChat.Conversation) => JSX.Element` |
| Default | Built-in trailing view                                  |

***

### usersStatusVisibility

Shows/hides the online/offline status indicator.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `true`    |

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Message List" icon="message" href="/ui-kit/react-native/message-list">
    Display the full chat interface after selecting a conversation
  </Card>

  <Card title="Users" icon="users" href="/ui-kit/react-native/users">
    Display and interact with user lists
  </Card>

  <Card title="Groups" icon="user-group" href="/ui-kit/react-native/groups">
    Display and manage group conversations
  </Card>

  <Card title="Component Styling" icon="paintbrush" href="/ui-kit/react-native/component-styling">
    Customize the appearance of UI Kit components
  </Card>
</CardGroup>