Conversations - CometChat Docs

AI Integration Quick Reference

{
  "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"
    }
  }
}

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.

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" },
});

Minimal Render

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().

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 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.

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.

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.

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).

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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 for mention formatting.

Common Patterns

Custom empty state with CTA

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

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

import { CometChatConversations } from "@cometchat/chat-uikit-react-native";

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

Multi-select with submit

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.

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

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.

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

Message List

Display the full chat interface after selecting a conversation

Users

Display and interact with user lists

Groups

Display and manage group conversations

Component Styling

Customize the appearance of UI Kit components

​Where It Fits

​Minimal Render

​Filtering Conversations

​Filter Recipes

​Actions and Events

​Callback Props

​onItemPress

​onItemLongPress

​onSelection

​onError

​onEmpty

​onLoad

​Global UI Events

​SDK Events (Real-Time, Automatic)

​Custom View Slots

​ItemView

​LeadingView

​TrailingView

​TitleView

​SubtitleView

​AppBarOptions

​options

​addOptions

​datePattern

​textFormatters

​Common Patterns

​Custom empty state with CTA

​Hide all chrome — minimal list

​Conversations with search

​Multi-select with submit

​Styling

​Style Properties

​Props

​conversationsRequestBuilder

​customSoundForMessages

​datePattern

​deleteConversationOptionVisibility

​disableSoundForMessages

​EmptyView

​ErrorView

​groupTypeVisibility

​hideBackButton

​hideError

​hideHeader

​hideSubmitButton

​ItemView

​LeadingView

​LoadingView

​onBack

​onEmpty

​onError

​onItemLongPress

​onItemPress

​onLoad

​onSearchBarClicked

​onSearchTextChanged

​onSelection

​onSubmit

​receiptsVisibility

​SearchView

​selectionMode

​searchText

​showSearchBar

​SubtitleView

​textFormatters

​TitleView

​TrailingView

​usersStatusVisibility

​Next Steps

Message List

Users

Groups

Component Styling

Where It Fits

Minimal Render

Filtering Conversations

Filter Recipes

Actions and Events

Callback Props

onItemPress

onItemLongPress

onSelection

onError

onEmpty

onLoad

Global UI Events

SDK Events (Real-Time, Automatic)

Custom View Slots

ItemView

LeadingView

TrailingView

TitleView

SubtitleView

AppBarOptions

options

addOptions

datePattern

textFormatters

Common Patterns

Custom empty state with CTA

Hide all chrome — minimal list

Conversations with search

Multi-select with submit

Styling

Style Properties

Props

conversationsRequestBuilder

customSoundForMessages

datePattern

deleteConversationOptionVisibility

disableSoundForMessages

EmptyView

ErrorView

groupTypeVisibility

hideBackButton

hideError

hideHeader

hideSubmitButton

ItemView

LeadingView

LoadingView

onBack

onEmpty

onError

onItemLongPress

onItemPress

onLoad

onSearchBarClicked

onSearchTextChanged

onSelection

onSubmit

receiptsVisibility

SearchView

selectionMode

searchText

showSearchBar

SubtitleView

textFormatters

TitleView

TrailingView

usersStatusVisibility

Next Steps