Conversations - CometChat Docs

AI Integration Quick Reference

{
  "component": "CometChatConversations",
  "package": "@cometchat/chat-uikit-react",
  "import": "import { CometChatConversations } from \"@cometchat/chat-uikit-react\";",
  "cssImport": "import \"@cometchat/chat-uikit-react/css-variables.css\";",
  "description": "Scrollable list of recent one-on-one and group conversations for the logged-in user with real-time updates.",
  "cssRootClass": ".cometchat-conversations",
  "primaryOutput": {
    "prop": "onItemClick",
    "type": "(conversation: CometChat.Conversation) => void"
  },
  "props": {
    "data": {
      "conversationsRequestBuilder": {
        "type": "CometChat.ConversationsRequestBuilder",
        "default": "SDK default (30 per page)",
        "note": "Pass the builder instance, not the result of .build()"
      },
      "searchRequestBuilder": {
        "type": "CometChat.ConversationsRequestBuilder",
        "default": "undefined"
      },
      "searchKeyword": {
        "type": "string",
        "default": "undefined"
      },
      "activeConversation": {
        "type": "CometChat.Conversation",
        "default": "undefined"
      },
      "lastMessageDateTimeFormat": {
        "type": "CometChatDateFormatConfig",
        "default": "hh:mm A today, Yesterday, dddd last week, DD/MM/YYYY older"
      }
    },
    "callbacks": {
      "onItemClick": "(conversation: CometChat.Conversation) => void",
      "onSelect": "(conversation: CometChat.Conversation, selected: boolean) => void",
      "onError": "((error: CometChat.CometChatException) => void) | null",
      "onEmpty": "() => void",
      "onSearchBarClicked": "() => void"
    },
    "visibility": {
      "hideReceipts": { "type": "boolean", "default": false },
      "hideUserStatus": { "type": "boolean", "default": false },
      "hideGroupType": { "type": "boolean", "default": false },
      "hideUnreadCount": { "type": "boolean", "default": false },
      "hideDeleteConversation": { "type": "boolean", "default": false },
      "showSearchBar": { "type": "boolean", "default": true },
      "showScrollbar": { "type": "boolean", "default": false }
    },
    "sound": {
      "disableSoundForMessages": { "type": "boolean", "default": false },
      "customSoundForMessages": { "type": "string", "default": "built-in" }
    },
    "selection": {
      "selectionMode": {
        "type": "CometChatConversationsSelectionMode",
        "values": ["'none'", "'single'", "'multiple'"],
        "default": "'none'"
      }
    },
    "viewSlots": {
      "itemView": "(conversation: CometChat.Conversation) => ReactNode",
      "leadingView": "(conversation: CometChat.Conversation) => ReactNode",
      "titleView": "(conversation: CometChat.Conversation) => ReactNode",
      "subtitleView": "(conversation: CometChat.Conversation) => ReactNode",
      "trailingView": "(conversation: CometChat.Conversation) => ReactNode",
      "headerView": "ReactNode",
      "searchView": "ReactNode",
      "loadingView": "ReactNode",
      "emptyView": "ReactNode",
      "errorView": "ReactNode",
      "options": "(conversation: CometChat.Conversation) => CometChatConversationOption[]"
    }
  },
  "events": [
    {
      "name": "ui:conversation/deleted",
      "payload": "{ conversation: CometChat.Conversation }",
      "description": "Conversation deleted from list"
    }
  ],
  "sdkListeners": [
    "onTextMessageReceived",
    "onMediaMessageReceived",
    "onCustomMessageReceived",
    "onInteractiveMessageReceived",
    "onTypingStarted",
    "onTypingEnded",
    "onMessagesDelivered",
    "onMessagesRead",
    "onUserOnline",
    "onUserOffline",
    "onGroupMemberJoined",
    "onGroupMemberLeft",
    "onGroupMemberKicked",
    "onGroupMemberBanned",
    "onMemberAddedToGroup"
  ],
  "types": {
    "CometChatDateFormatConfig": {
      "today": "string | undefined",
      "yesterday": "string | undefined",
      "lastWeek": "string | undefined",
      "otherDays": "string | undefined",
      "relativeTime": {
        "minute": "string | undefined",
        "minutes": "string | undefined",
        "hour": "string | undefined",
        "hours": "string | undefined"
      }
    },
    "CometChatConversationOption": {
      "id": "string",
      "title": "string",
      "iconURL": "string | undefined",
      "onClick": "(conversation: CometChat.Conversation) => void"
    },
    "CometChatConversationsSelectionMode": "'none' | 'single' | 'multiple'"
  }
}

Overview

CometChatConversations is a sidebar list component. It renders recent conversations for the logged-in user and emits the selected CometChat.Conversation via onItemClick. Wire it to CometChatMessageHeader, CometChatMessageList, and CometChatMessageComposer to build a standard two-panel chat layout.

Live Preview — interact with the default conversations list.Open in Storybook ↗

The component handles:

Paginated fetching with infinite scroll
Real-time updates (new messages, typing indicators, presence changes)
Search filtering
Swipe/hover options (delete conversation)
Selection mode (single/multiple)

Usage

Flat API

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

function Sidebar() {
  return (
    <CometChatConversations
      onItemClick={(conversation) => {
        const entity = conversation.getConversationWith();
        // Pass entity to MessageHeader, MessageList, MessageComposer
      }}
    />
  );
}

Compound Composition

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

function Sidebar() {
  return (
    <CometChatConversations.Root onItemClick={handleClick}>
      <CometChatConversations.Header title="Messages" />
      <CometChatConversations.SearchBar placeholder="Find a conversation..." />
      <CometChatConversations.LoadingState />
      <CometChatConversations.ErrorState />
      <CometChatConversations.EmptyState>
        <p>No conversations yet. Start a new chat!</p>
      </CometChatConversations.EmptyState>
      <CometChatConversations.List />
    </CometChatConversations.Root>
  );
}

Full Layout Example

import { useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import {
  CometChatConversations,
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
} from "@cometchat/chat-uikit-react";

function ChatApp() {
  const [user, setUser] = useState<CometChat.User | undefined>();
  const [group, setGroup] = useState<CometChat.Group | undefined>();

  const handleConversationClick = (conversation: CometChat.Conversation) => {
    const entity = conversation.getConversationWith();
    if (conversation.getConversationType() === "user") {
      setUser(entity as CometChat.User);
      setGroup(undefined);
    } else {
      setGroup(entity as CometChat.Group);
      setUser(undefined);
    }
  };

  return (
    <div style={{ display: "flex", height: "100vh" }}>
      <div style={{ width: 360 }}>
        <CometChatConversations onItemClick={handleConversationClick} />
      </div>
      <div style={{ flex: 1, display: "flex", flexDirection: "column" }}>
        <CometChatMessageHeader user={user} group={group} />
        <CometChatMessageList user={user} group={group} />
        <CometChatMessageComposer user={user} group={group} />
      </div>
    </div>
  );
}

Filtering

Pass a CometChat.ConversationsRequestBuilder to conversationsRequestBuilder to control which conversations load. Pass the builder instance — not the result of .build().

<CometChatConversations
  conversationsRequestBuilder={
    new CometChat.ConversationsRequestBuilder()
      .setLimit(15)
      .setConversationType("user")
  }
/>

Search

The component includes a built-in search bar. When the user types, it filters conversations client-side by name. For server-side search, pass a searchRequestBuilder:

<CometChatConversations
  searchRequestBuilder={
    new CometChat.ConversationsRequestBuilder().setLimit(30)
  }
/>

To use the search bar as a trigger for a custom search UI (like CometChatSearch), pass onSearchBarClicked:

<CometChatConversations
  onSearchBarClicked={() => openGlobalSearch()}
/>

Filter Recipes

Recipe	Code
Only 1-on-1 chats	`new CometChat.ConversationsRequestBuilder().setConversationType("user")`
Only group chats	`new CometChat.ConversationsRequestBuilder().setConversationType("group")`
Limit page size	`new CometChat.ConversationsRequestBuilder().setLimit(10)`
With tags	`new CometChat.ConversationsRequestBuilder().setTags(["support"])`

Actions and Events

Callback Props

Prop	Signature	Fires when
`onItemClick`	`(conversation: CometChat.Conversation) => void`	User clicks a conversation item
`onSelect`	`(conversation: CometChat.Conversation, selected: boolean) => void`	Conversation selected/deselected (selection mode)
`onError`	`((error: CometChat.CometChatException) => void) \| null`	SDK error occurs
`onEmpty`	`() => void`	List is empty after initial fetch
`onSearchBarClicked`	`() => void`	Search bar is clicked (makes input read-only)

Events Emitted

UI events this component publishes:

Event	Payload	Fires when
`ui:conversation/deleted`	`{ conversation }`	User deletes a conversation

Events Received

UI events this component subscribes to (published by other components):

Event	Payload	Behavior
`ui:message/sent`	`{ message, status }`	Moves conversation to top, updates last message, resets unread count
`ui:compose/edit`	`{ message, status }`	Updates the conversation’s last message
`ui:message/deleted`	`{ message }`	Updates the conversation’s last message
`ui:message/read`	`{ message }`	Resets unread count for that conversation
`ui:conversation/updated`	`{ conversation }`	Updates the conversation in the list
`ui:conversation/read`	`{ conversationId }`	Resets unread count by conversation ID
`ui:conversation/deleted`	`{ conversation }`	Removes the conversation from the list
`ui:group/created`	`{ group }`	Adds the new group conversation to the list
`ui:group/deleted`	`{ group }`	Removes the group conversation from the list
`ui:group/left`	`{ group }`	Removes the group conversation from the list
`ui:group/member-added`	`{ group, members, messages }`	Updates last message and moves to top
`ui:group/member-kicked`	`{ group, member, message }`	Updates last message and moves to top
`ui:group/member-banned`	`{ group, member, message }`	Updates last message and moves to top
`ui:group/member-unbanned`	`{ group, member, message }`	Updates last message and moves to top

SDK Listeners (Automatic)

These SDK listeners are attached internally. The component updates its state automatically — no manual subscription needed:

Message listeners: onTextMessageReceived, onMediaMessageReceived, onCustomMessageReceived, onInteractiveMessageReceived
Typing: onTypingStarted, onTypingEnded
Receipts: onMessagesDelivered, onMessagesRead
Presence: onUserOnline, onUserOffline
Groups: onGroupMemberJoined, onGroupMemberLeft, onGroupMemberKicked, onGroupMemberBanned, onMemberAddedToGroup

Customization

View Props

Use view props to replace sections of the default UI while keeping the component’s behavior intact:

<CometChatConversations
  headerView={<MyCustomHeader />}
  itemView={(conversation) => <MyCustomItem conversation={conversation} />}
  emptyView={<EmptyState />}
  loadingView={<Skeleton />}
  errorView={<ErrorBanner />}
/>

Slot	Signature	Replaces
`itemView`	`(conversation) => ReactNode`	Entire conversation row
`leadingView`	`(conversation) => ReactNode`	Avatar section
`titleView`	`(conversation) => ReactNode`	Conversation name
`subtitleView`	`(conversation) => ReactNode`	Last message preview
`trailingView`	`(conversation) => ReactNode`	Timestamp + unread badge
`headerView`	`ReactNode`	Header area
`searchView`	`ReactNode`	Search bar
`loadingView`	`ReactNode`	Loading shimmer
`emptyView`	`ReactNode`	Empty state
`errorView`	`ReactNode`	Error state

Compound Composition

For full layout control, use sub-components. Omit any sub-component to hide it:

<CometChatConversations.Root onItemClick={handleClick}>
  {/* No Header or SearchBar — they won't render */}
  <CometChatConversations.List />
</CometChatConversations.Root>

Available sub-components:

Sub-component	Description	Props	Flat API equivalent
`Root`	Context provider and container	All Root props + `children`	—
`List`	Scrollable conversation list	`itemView`, `className`	`itemView`
`Item`	Individual conversation row	`leadingView`, `titleView`, `subtitleView`, `trailingView`, `className`	Per-item view props
`Header`	Header area	`title`, `children`	`headerView`
`SearchBar`	Search input	`placeholder`, `onClick`	`searchView`
`EmptyState`	Empty state	`children`	`emptyView`
`ErrorState`	Error state	`children`	`errorView`
`LoadingState`	Loading shimmer	`children`	`loadingView`

CSS Styling

Override design tokens on the component selector:

.cometchat-conversations {
  --cometchat-background-color-01: #1a1a2e;
  --cometchat-text-color-primary: #ffffff;
}

.cometchat-conversations__item--active {
  background: var(--cometchat-primary-color);
}

Props

All props are optional.

View slot props (headerView, searchView, loadingView, emptyView, errorView, itemView, leadingView, titleView, subtitleView, trailingView) are convenience props available only on the flat API. In compound composition mode, use the corresponding sub-components directly.

conversationsRequestBuilder

Custom request builder for fetching conversations. Controls pagination, filtering, and sorting.


Type	`CometChat.ConversationsRequestBuilder`
Default	SDK default (limit 30)

searchRequestBuilder

Custom request builder used specifically when the user searches. Separate from the main builder.


Type	`CometChat.ConversationsRequestBuilder`
Default	`undefined`

searchKeyword

Initial search keyword to pre-filter conversations on mount.


Type	`string`
Default	`undefined`

activeConversation

The currently active/highlighted conversation. The matching item receives an active visual state.


Type	`CometChat.Conversation`
Default	`undefined`

lastMessageDateTimeFormat

Custom date/time format for the last message timestamp shown in each conversation item.


Type	`CometChatDateFormatConfig`
Default	`{ today: 'hh:mm A', yesterday: 'Yesterday', lastWeek: 'dddd', otherDays: 'DD/MM/YYYY' }`

hideReceipts

Hide message delivery/read receipts (double ticks) on conversation items.


Type	`boolean`
Default	`false`

hideUserStatus

Hide the online/offline status indicator on user avatars.


Type	`boolean`
Default	`false`

hideGroupType

Hide the group type indicator (public/private/password) on group conversation items.


Type	`boolean`
Default	`false`

hideUnreadCount

Hide the unread message count badge.


Type	`boolean`
Default	`false`

hideDeleteConversation

Hide the delete option in the conversation item’s context menu.


Type	`boolean`
Default	`false`

showSearchBar

Whether to show the search bar. Set to false to hide it entirely.


Type	`boolean`
Default	`true`

showScrollbar

Show the native scrollbar on the conversation list.


Type	`boolean`
Default	`false`

selectionMode

Enable selection mode for multi-select operations.


Type	`'none' \| 'single' \| 'multiple'`
Default	`'none'`

disableSoundForMessages

Disable the notification sound when new messages arrive.


Type	`boolean`
Default	`false`

customSoundForMessages

Custom sound URL to play when new messages arrive (replaces the built-in sound).


Type	`string`
Default	Built-in notification sound

options

Function that returns context menu options for each conversation item (shown on hover/swipe).


Type	`(conversation: CometChat.Conversation) => CometChatConversationOption[]`
Default	Default options (delete)

<CometChatConversations
  options={(conversation) => [
    {
      id: "pin",
      title: "Pin",
      iconURL: pinIcon,
      onClick: (conv) => pinConversation(conv),
    },
    {
      id: "mute",
      title: "Mute",
      iconURL: muteIcon,
      onClick: (conv) => muteConversation(conv),
    },
  ]}
/>

onItemClick

Callback when a conversation item is clicked.


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

onSelect

Callback when a conversation is selected or deselected (only fires in selection mode).


Type	`(conversation: CometChat.Conversation, selected: boolean) => void`
Default	`undefined`

onError

Callback when an SDK error occurs during fetch or real-time operations.


Type	`((error: CometChat.CometChatException) => void) \| null`
Default	`null`

onEmpty

Callback when the conversation list is empty after the initial fetch completes.


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

onSearchBarClicked

Callback when the search bar is clicked. When provided, the search input becomes read-only and acts as a trigger (useful for opening a global search component like CometChatSearch).


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

CSS Selectors

Target	Selector
Root container	`.cometchat-conversations`
Header	`.cometchat-conversations__header`
Search bar	`.cometchat-conversations__search-bar`
List container	`.cometchat-conversations__list`
Conversation item	`.cometchat-conversations__item`
Active item	`.cometchat-conversations__item--active`
Item avatar	`.cometchat-conversations__item-avatar`
Item title	`.cometchat-conversations__item-title`
Item subtitle	`.cometchat-conversations__item-subtitle`
Item trailing	`.cometchat-conversations__item-trailing`
Unread badge	`.cometchat-conversations__item-unread-count`
Empty state	`.cometchat-conversations__empty-state`
Error state	`.cometchat-conversations__error-state`
Loading state	`.cometchat-conversations__loading-state`

Next Steps

Users

Browse and select users for new conversations

Message List

Display messages for the selected conversation

Search

Search across conversations and messages

Theming

Customize colors, fonts, and spacing

Documentation Index

​Overview

​Usage

​Flat API

​Compound Composition

​Full Layout Example

​Filtering

​Search

​Filter Recipes

​Actions and Events

​Callback Props

​Events Emitted

​Events Received

​SDK Listeners (Automatic)

​Customization

​View Props

​Compound Composition

​CSS Styling

​Props

​conversationsRequestBuilder

​searchRequestBuilder

​searchKeyword

​activeConversation

​lastMessageDateTimeFormat

​hideReceipts

​hideUserStatus

​hideGroupType

​hideUnreadCount

​hideDeleteConversation

​showSearchBar

​showScrollbar

​selectionMode

​disableSoundForMessages

​customSoundForMessages

​options

​onItemClick

​onSelect

​onError

​onEmpty

​onSearchBarClicked

​CSS Selectors

​Next Steps

Users

Message List

Search

Theming

Overview

Usage

Flat API

Compound Composition

Full Layout Example

Filtering

Search

Filter Recipes

Actions and Events

Callback Props

Events Emitted

Events Received

SDK Listeners (Automatic)

Customization

View Props

Compound Composition

CSS Styling

Props

conversationsRequestBuilder

searchRequestBuilder

searchKeyword

activeConversation

lastMessageDateTimeFormat

hideReceipts

hideUserStatus

hideGroupType

hideUnreadCount

hideDeleteConversation

showSearchBar

showScrollbar

selectionMode

disableSoundForMessages

customSoundForMessages

options

onItemClick

onSelect

onError

onEmpty

onSearchBarClicked

CSS Selectors

Next Steps