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

itemView

Replace the entire list item row. Default:

Customized:

TypeScript
CSS

import { CometChat } from "@cometchat/chat-sdk-javascript";
import {
  CometChatConversations,
  CometChatAvatar,
  CometChatDate,
} from "@cometchat/chat-uikit-react";

function CustomItemViewConversations() {
  const getItemView = (conversation: CometChat.Conversation) => {
    const title = conversation.getConversationWith().getName();
    const timestamp = conversation?.getLastMessage()?.getSentAt();

    return (
      <div className="conversations__custom-item">
        <CometChatAvatar.Root name={title}>
          <CometChatAvatar.Image />
          <CometChatAvatar.Initials />
        </CometChatAvatar.Root>
        <span className="conversations__custom-item-title">{title}</span>
        {timestamp ? (
          <CometChatDate.Root timestamp={timestamp}>
            <CometChatDate.Text />
          </CometChatDate.Root>
        ) : null}
      </div>
    );
  };

  return <CometChatConversations itemView={getItemView} />;
}

.conversations__custom-item {
  display: flex;
  align-items: center;
  gap: 8px;
  padding: 8px 16px;
  width: 100%;
}

.conversations__custom-item-title {
  flex: 1;
  font: 500 16px/19.2px Roboto;
  color: #141414;
}

.cometchat-conversations .cometchat-avatar {
  border-radius: 8px;
  width: 32px;
  height: 32px;
}

leadingView

Replace the avatar / left section. Typing-aware avatar example.

import { useEffect, useRef, useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import {
  CometChatConversations,
  CometChatAvatar,
  useLoggedInUser,
} from "@cometchat/chat-uikit-react";

function TypingAwareConversations() {
  const [isTyping, setIsTyping] = useState(false);
  const typingObjRef = useRef<CometChat.TypingIndicator | null>(null);
  const loggedInUser = useLoggedInUser();

  useEffect(() => {
    const listenerId = "typing_demo_" + Date.now();
    CometChat.addMessageListener(
      listenerId,
      new CometChat.MessageListener({
        onTypingStarted: (typingIndicator: CometChat.TypingIndicator) => {
          typingObjRef.current = typingIndicator;
          setIsTyping(true);
        },
        onTypingEnded: (typingIndicator: CometChat.TypingIndicator) => {
          if (
            typingObjRef.current &&
            typingObjRef.current.getSender().getUid() ===
              typingIndicator.getSender().getUid()
          ) {
            typingObjRef.current = null;
            setIsTyping(false);
          }
        },
      })
    );
    return () => {
      CometChat.removeMessageListener(listenerId);
    };
  }, []);

  const getLeadingView = (conversation: CometChat.Conversation) => {
    const entity = conversation.getConversationWith();
    const isUser = entity instanceof CometChat.User;
    const isGroup = entity instanceof CometChat.Group;

    const isMyTyping = isUser
      ? (entity as CometChat.User).getUid() ===
          typingObjRef.current?.getSender().getUid() &&
        loggedInUser?.getUid() === typingObjRef.current?.getReceiverId()
      : isGroup &&
        (entity as CometChat.Group).getGuid() ===
          typingObjRef.current?.getReceiverId();

    const avatar = isUser
      ? (entity as CometChat.User).getAvatar()
      : (entity as CometChat.Group).getIcon();

    return (
      <div className="conversations__leading-view">
        <CometChatAvatar.Root
          image={isTyping && isMyTyping ? undefined : avatar}
          name={isTyping && isMyTyping ? undefined : entity.getName()}
        >
          <CometChatAvatar.Image />
          <CometChatAvatar.Initials />
        </CometChatAvatar.Root>
      </div>
    );
  };

  return <CometChatConversations leadingView={getLeadingView} />;
}

titleView

Replace the name / title text. Inline user status example.

TypeScript
CSS

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

function StatusTitleConversations() {
  const getTitleView = (conversation: CometChat.Conversation) => {
    const user =
      conversation.getConversationType() === "user"
        ? (conversation.getConversationWith() as CometChat.User)
        : undefined;

    return (
      <div className="conversations__title-view">
        <span className="conversations__title-view-name">
          {user
            ? conversation.getConversationWith().getName() + " · "
            : conversation.getConversationWith().getName()}
        </span>
        {user && (
          <span className="conversations__title-view-status">
            {user.getStatusMessage()}
          </span>
        )}
      </div>
    );
  };

  return <CometChatConversations titleView={getTitleView} />;
}

.cometchat-conversations .conversations__title-view {
  display: flex;
  gap: 4px;
  width: 100%;
}

.conversations__title-view-name {
  color: #141414;
  font: 500 16px/19.2px Roboto;
}

.conversations__title-view-status {
  color: #6852d6;
  font: 400 16px/19.2px Roboto;
}

subtitleView

Replace the last message preview text. Default:

Customized:

TypeScript
CSS

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

function formatTimestamp(timestamp: number): string {
  return new Date(timestamp * 1000).toLocaleString();
}

function SubtitleConversations() {
  const getSubtitleView = (conversation: CometChat.Conversation) => {
    if (conversation.getConversationType() === "user") {
      return (
        <span className='custom-conversation-subtitle'>
          Last active:{" "}
          {new Date(
            (conversation.getConversationWith() as CometChat.User).getLastActiveAt() * 1000
          ).toLocaleString()}
        </span>
      );
    }
    return (
      <span className='custom-conversation-subtitle'>
        Created:{" "}
        {new Date(
          (conversation.getConversationWith() as CometChat.Group).getCreatedAt() * 1000
        ).toLocaleString()}
      </span>
    );
  };

  return <CometChatConversations subtitleView={getSubtitleView} />;
}

.custom-conversation-subtitle {
  overflow: hidden;
  color: grey;
  text-overflow: ellipsis;
  white-space: nowrap;
  font: var(--cometchat-font-body-regular);
}

trailingView

Replace the timestamp / badge / right section. Relative time badge example.

TypeScript
CSS

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

function RelativeTimeConversations() {
  const getTrailingView = (conv: CometChat.Conversation) => {
    if (!conv.getLastMessage()) return <></>;

    const timestamp = conv.getLastMessage()?.getSentAt() * 1000;
    const now = Date.now();
    const diffInMinutes = Math.floor((now - timestamp) / (1000 * 60));
    const diffInHours = Math.floor((now - timestamp) / (1000 * 60 * 60));

    let className = "conversations__trailing-view-min";
    let topLabel = `${diffInMinutes}`;
    let bottomLabel = diffInMinutes === 1 ? "Min ago" : "Mins ago";

    if (diffInHours >= 1 && diffInHours <= 10) {
      className = "conversations__trailing-view-hour";
      topLabel = `${diffInHours}`;
      bottomLabel = diffInHours === 1 ? "Hour ago" : "Hours ago";
    } else if (diffInHours > 10) {
      className = "conversations__trailing-view-date";
      const time = new Date(timestamp);
      topLabel = time.toLocaleDateString("en-US", { day: "numeric" });
      bottomLabel = time.toLocaleDateString("en-US", { month: "short", year: "numeric" });
    }

    return (
      <div className={`conversations__trailing-view ${className}`}>
        <span className="conversations__trailing-view-time">{topLabel}</span>
        <span className="conversations__trailing-view-status">{bottomLabel}</span>
      </div>
    );
  };

  return <CometChatConversations trailingView={getTrailingView} />;
}

.conversations__trailing-view {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  width: 55px;
  height: 40px;
  border-radius: 8px;
  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
}

.conversations__trailing-view-min { background-color: #e0d4f7; }
.conversations__trailing-view-hour { background-color: #fff3cd; }
.conversations__trailing-view-date { background-color: #f8d7da; }

.conversations__trailing-view-time {
  font: 600 18px Roboto;
  color: #4a3f99;
  margin-bottom: 4px;
}

.conversations__trailing-view-status {
  font: 600 8px Roboto;
  color: #6a5b99;
}

.cometchat-conversations .cometchat-list-item__trailing-view {
  height: 50px;
}

headerView

Replace the entire header bar.

TypeScript
CSS

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

function CustomHeaderConversations() {
  const { getLocalizedString } = useLocale();

  return (
    <CometChatConversations
      headerView={
        <div className="conversations__header">
          <div className="conversations__header__title">
            {getLocalizedString("chats")}
          </div>
          <CometChatButton.Root onClick={() => { /* handle click */ }}>
            <CometChatButton.Icon />
          </CometChatButton.Root>
        </div>
      }
    />
  );
}

.conversations__header {
  display: flex;
  width: 100%;
  padding: 8px 16px;
  align-items: center;
  justify-content: space-between;
  gap: 12px;
  border-radius: 10px;
  border: 1px solid #e8e8e8;
  background: #edeafa;
}

.conversations__header__title {
  overflow: hidden;
  color: #141414;
  text-overflow: ellipsis;
  font: 700 24px Roboto;
}

.conversations__header .cometchat-button .cometchat-button__icon {
  background: #141414;
}

.conversations__header .cometchat-button {
  width: 24px;
  border: none;
  background: transparent;
  border-radius: 0;
}

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

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 Architecture

The component uses CSS custom properties (design tokens) that are bundled with @cometchat/chat-uikit-react. The cascade:

Global tokens (e.g., --cometchat-primary-color, --cometchat-background-color-01) are set on the .cometchat root wrapper.
Component CSS (.cometchat-conversations) consumes these tokens via var() with fallback values.
Overrides target .cometchat-conversations descendant selectors in a global stylesheet.

To scope overrides to a single instance when multiple CometChatConversations exist on the same page, wrap the component in a container and scope selectors:

.sidebar-left .cometchat-conversations .cometchat-badge {
  background: #e5484d;
}

Overrides survive component updates because the component never sets inline styles on these elements — all styling flows through CSS classes and custom properties.

Key Selectors

Target	Selector
Root	`.cometchat-conversations`
Header title	`.cometchat-conversations .cometchat-list__header-title`
List item	`.cometchat-conversations .cometchat-list-item`
Body title	`.cometchat-conversations .cometchat-list-item__body-title`
Avatar	`.cometchat-conversations .cometchat-avatar`
Avatar text	`.cometchat-conversations .cometchat-avatar__text`
Unread badge	`.cometchat-conversations .cometchat-badge`
Subtitle text	`.cometchat-conversations .cometchat-conversations__subtitle-text`
Status indicator	`.cometchat-conversations .cometchat-status-indicator`
Read receipts	`.cometchat-conversations .cometchat-receipts-read`
Active item	`.cometchat-conversations__list-item-active .cometchat-list-item`
Typing indicator	`.cometchat-conversations__subtitle-typing`
Trailing view	`.cometchat-conversations__trailing-view`

Example: Brand-themed conversations

.cometchat-conversations .cometchat-conversations__item-title,
.cometchat-conversations .cometchat-conversations__header-title,
.cometchat-conversations .cometchat-avatar__text,
.cometchat-conversations .cometchat-conversations__item-unread-badge,
.cometchat-conversations .cometchat-conversations__item-subtitle-text {
  font-family: "SF Pro";
}

.cometchat-conversations .cometchat-conversations__header {
  background: #fef8f8;
  border-bottom: 2px solid #f4b6b8;
}

.cometchat-conversations .cometchat-avatar {
  background: #FAAA75;
}

.cometchat-conversations .cometchat-status-indicator {
  min-width: 10px;
  height: 10px;
}

.cometchat-conversations .cometchat-conversations__item-unread-badge {
  background: #F76809;
}

.cometchat-conversations .cometchat-conversations__item-receipt--read {
  background: #FAAA75;
}

Customization Matrix

What to change	Where	Property/API	Example
Override behavior on user interaction	Component props	`on<Event>` callbacks	`onItemClick={(c) => setActive(c)}`
Filter which conversations appear	Component props	`conversationsRequestBuilder`	`conversationsRequestBuilder={new CometChat.ConversationsRequestBuilder().setLimit(10)}`
Toggle visibility of UI elements	Component props	`hide<Feature>` boolean props	`hideReceipts={true}`
Replace a section of the list item	Component props	`<slot>View` render props	`itemView={(conversation) => <div>...</div>}`
Change colors, fonts, spacing	Global CSS	Target `.cometchat-conversations` class	`.cometchat-conversations .cometchat-badge { background: #e5484d; }`

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

​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

​itemView

​leadingView

​titleView

​subtitleView

​trailingView

​headerView

​Compound Composition

​CSS Styling

​Props

​conversationsRequestBuilder

​searchRequestBuilder

​searchKeyword

​activeConversation

​lastMessageDateTimeFormat

​hideReceipts

​hideUserStatus

​hideGroupType

​hideUnreadCount

​hideDeleteConversation

​showSearchBar

​showScrollbar

​selectionMode

​disableSoundForMessages

​customSoundForMessages

​onItemClick

​onSelect

​onError

​onEmpty

​onSearchBarClicked

​CSS Architecture

​Key Selectors

​Example: Brand-themed conversations

​Customization Matrix

​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

itemView

leadingView

titleView

subtitleView

trailingView

headerView

Compound Composition

CSS Styling

Props

conversationsRequestBuilder

searchRequestBuilder

searchKeyword

activeConversation

lastMessageDateTimeFormat

hideReceipts

hideUserStatus

hideGroupType

hideUnreadCount

hideDeleteConversation

showSearchBar

showScrollbar

selectionMode

disableSoundForMessages

customSoundForMessages

onItemClick

onSelect

onError

onEmpty

onSearchBarClicked

CSS Architecture

Key Selectors

Example: Brand-themed conversations

Customization Matrix

Next Steps