Message List - CometChat Docs

AI Integration Quick Reference

{
  "component": "CometChatMessageList",
  "package": "@cometchat/chat-uikit-react",
  "import": "import { CometChatMessageList } from \"@cometchat/chat-uikit-react\";",
  "description": "Scrollable message feed with plugin-based bubble rendering, reactions, receipts, threads, and real-time updates.",
  "cssRootClass": ".cometchat-message-list",
  "primaryOutput": {
    "prop": "onThreadRepliesClick",
    "type": "(message: CometChat.BaseMessage) => void"
  },
  "props": {
    "entity": {
      "user": {
        "type": "CometChat.User",
        "default": "undefined",
        "note": "For 1-on-1 chat. Mutually exclusive with group."
      },
      "group": {
        "type": "CometChat.Group",
        "default": "undefined",
        "note": "For group chat. Mutually exclusive with user."
      },
      "parentMessageId": {
        "type": "number",
        "default": "undefined",
        "note": "Enables thread mode — fetches replies to this message."
      }
    },
    "data": {
      "messagesRequestBuilder": {
        "type": "CometChat.MessagesRequestBuilder",
        "default": "SDK default (limit 30)",
        "note": "Pass the builder instance, not the result of .build()"
      },
      "reactionsRequestBuilder": {
        "type": "CometChat.ReactionsRequestBuilder",
        "default": "undefined"
      },
      "messageTypes": {
        "type": "string[]",
        "default": "Plugin registry types"
      },
      "messageCategories": {
        "type": "string[]",
        "default": "Plugin registry categories"
      },
      "goToMessageId": {
        "type": "number",
        "default": "undefined",
        "note": "Jump to a specific message (e.g., from search or deep link)"
      },
      "startFromUnreadMessages": {
        "type": "boolean",
        "default": false
      },
      "loadLastAgentConversation": {
        "type": "boolean",
        "default": false
      }
    },
    "visibility": {
      "hideReceipts": { "type": "boolean", "default": false },
      "hideStickyDate": { "type": "boolean", "default": false },
      "hideDateSeparator": { "type": "boolean", "default": false },
      "hideAvatar": { "type": "boolean", "default": false },
      "hideGroupActionMessages": { "type": "boolean", "default": false },
      "hideModerationView": { "type": "boolean", "default": false },
      "showScrollbar": { "type": "boolean", "default": false },
      "showSmartReplies": { "type": "boolean", "default": false },
      "showConversationStarters": { "type": "boolean", "default": false },
      "showMarkAsUnreadOption": { "type": "boolean", "default": false },
      "disableTruncation": { "type": "boolean", "default": false },
      "isAgentChat": { "type": "boolean", "default": false }
    },
    "optionToggles": {
      "hideReplyOption": { "type": "boolean", "default": false },
      "hideReplyInThreadOption": { "type": "boolean", "default": false },
      "hideEditMessageOption": { "type": "boolean", "default": false },
      "hideDeleteMessageOption": { "type": "boolean", "default": false },
      "hideCopyMessageOption": { "type": "boolean", "default": false },
      "hideReactionOption": { "type": "boolean", "default": false },
      "hideMessageInfoOption": { "type": "boolean", "default": false },
      "hideFlagMessageOption": { "type": "boolean", "default": false },
      "hideMessagePrivatelyOption": { "type": "boolean", "default": false },
      "hideTranslateMessageOption": { "type": "boolean", "default": false },
      "hideFlagRemarkField": { "type": "boolean", "default": false },
      "quickOptionsCount": { "type": "number", "default": 3 }
    },
    "dateFormatting": {
      "separatorDateTimeFormat": { "type": "CometChatDateFormatConfig" },
      "stickyDateTimeFormat": { "type": "CometChatDateFormatConfig" },
      "messageSentAtDateTimeFormat": { "type": "CometChatDateFormatConfig" },
      "messageInfoDateTimeFormat": { "type": "CometChatDateFormatConfig" }
    },
    "alignment": {
      "messageAlignment": {
        "type": "CometChatMessageListAlignment",
        "values": ["0 (left)", "1 (standard)"],
        "default": "1 (standard)"
      }
    },
    "sound": {
      "disableSoundForMessages": { "type": "boolean", "default": false },
      "customSoundForMessages": { "type": "string", "default": "built-in" }
    },
    "ai": {
      "smartRepliesKeywords": {
        "type": "string[]",
        "default": "['what','when','why','who','where','how','?']"
      },
      "smartRepliesDelayDuration": {
        "type": "number",
        "default": 10000
      }
    },
    "callbacks": {
      "onThreadRepliesClick": "(message: CometChat.BaseMessage) => void",
      "onAvatarClick": "(user: CometChat.User) => void",
      "onEditMessage": "(message: CometChat.BaseMessage) => void",
      "onReplyMessage": "(message: CometChat.BaseMessage) => void",
      "onReactionClick": "(reaction: CometChat.ReactionCount, message: CometChat.BaseMessage) => void",
      "onReactionListItemClick": "(reaction: CometChat.Reaction, message: CometChat.BaseMessage) => void",
      "onActiveChatChanged": "(data: { user?, group?, message?, unreadMessageCount? }) => void",
      "onMessageRead": "(message: CometChat.BaseMessage) => void",
      "onMessageDeleted": "(message: CometChat.BaseMessage) => void",
      "onConversationMarkedAsRead": "(conversation: CometChat.Conversation) => void",
      "onConversationUpdated": "(conversation: CometChat.Conversation) => void",
      "onError": "((error: CometChat.CometChatException) => void) | null"
    },
    "viewSlots": {
      "bubbleView": "(message: CometChat.BaseMessage, loggedInUser: CometChat.User) => ReactNode",
      "headerView": "ReactNode",
      "footerView": "ReactNode",
      "loadingView": "ReactNode",
      "emptyView": "ReactNode",
      "errorView": "ReactNode"
    }
  },
  "events": [
    {
      "name": "ui:message/read",
      "payload": "{ message }",
      "description": "Message marked as read"
    },
    {
      "name": "ui:message/deleted",
      "payload": "{ message }",
      "description": "Message deleted by user"
    },
    {
      "name": "ui:active-chat/changed",
      "payload": "{ user?, group?, message?, unreadMessageCount? }",
      "description": "Active chat context changed on init"
    },
    {
      "name": "ui:conversation/read",
      "payload": "{ conversationId }",
      "description": "Conversation marked as read"
    },
    {
      "name": "ui:conversation/updated",
      "payload": "{ conversation }",
      "description": "Conversation updated (mark-as-unread)"
    }
  ],
  "sdkListeners": [
    "onTextMessageReceived",
    "onMediaMessageReceived",
    "onCustomMessageReceived",
    "onInteractiveMessageReceived",
    "onTypingStarted",
    "onTypingEnded",
    "onMessagesDelivered",
    "onMessagesRead",
    "onMessagesDeliveredToAll",
    "onMessagesReadByAll",
    "onMessageEdited",
    "onMessageDeleted",
    "onTransientMessageReceived"
  ],
  "types": {
    "CometChatMessageListAlignment": {
      "left": 0,
      "standard": 1
    },
    "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"
      }
    }
  }
}

Overview

CometChatMessageList is a scrollable message feed component. It renders messages for a given user or group conversation and emits thread navigation via onThreadRepliesClick. Wire it between CometChatMessageHeader and CometChatMessageComposer to build a standard chat panel.

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

The component handles:

Paginated message fetching with infinite scroll (older messages load on scroll-up)
Plugin-based bubble rendering — each message type is rendered by a registered plugin
Reactions with emoji picker and reaction list
Read/delivery receipts (single and group)
Thread reply indicators with reply count
Real-time updates (new messages, edits, deletes, typing indicators)
Smart replies — AI-generated quick reply suggestions based on incoming messages
Conversation starters — AI-generated prompts when the conversation is empty
Date separators and sticky floating date header
Jump-to-message for search results and deep links
Mark-as-unread support

Note: user and group are mutually exclusive. Pass one or the other to specify the conversation context.

Usage

Flat API

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

function ChatPanel({ user }: { user: CometChat.User }) {
  return (
    <CometChatMessageList
      user={user}
      onThreadRepliesClick={(message) => openThread(message)}
    />
  );
}

Compound Composition

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

function ChatPanel({ group }: { group: CometChat.Group }) {
  return (
    <CometChatMessageList.Root group={group}>
      <CometChatMessageList.LoadingState />
      <CometChatMessageList.ErrorState />
      <CometChatMessageList.EmptyState />
      <CometChatMessageList.Header />
      <CometChatMessageList.View />
      <CometChatMessageList.Footer />
      <CometChatMessageList.AIFooter />
    </CometChatMessageList.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 [threadMessage, setThreadMessage] = useState<CometChat.BaseMessage | 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);
    }
    setThreadMessage(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}
          onThreadRepliesClick={(message) => setThreadMessage(message)}
        />
        <CometChatMessageComposer user={user} group={group} />
      </div>
      {threadMessage && (
        <div style={{ width: 400, display: "flex", flexDirection: "column" }}>
          <CometChatMessageList
            user={user}
            group={group}
            parentMessageId={threadMessage.getId()}
          />
          <CometChatMessageComposer
            user={user}
            group={group}
            parentMessageId={threadMessage.getId()}
          />
        </div>
      )}
    </div>
  );
}

Filtering

Pass a CometChat.MessagesRequestBuilder to messagesRequestBuilder to control which messages load. Pass the builder instance — not the result of .build(). Refer to MessagesRequestBuilder for the full builder API.

<CometChatMessageList
  user={user}
  messagesRequestBuilder={
    new CometChat.MessagesRequestBuilder()
      .setLimit(50)
      .setCategories(["message"])
      .setTypes(["text", "image", "video"])
  }
/>

Filter Recipes

Recipe	Code
Only text messages	`new CometChat.MessagesRequestBuilder().setTypes(["text"])`
Only media	`new CometChat.MessagesRequestBuilder().setTypes(["image", "video", "audio", "file"])`
Larger page size	`new CometChat.MessagesRequestBuilder().setLimit(50)`
Hide actions	`new CometChat.MessagesRequestBuilder().setCategories(["message"])`
With tags	`new CometChat.MessagesRequestBuilder().setTags(["important"])`

Actions and Events

Callback Props

Prop	Signature	Fires when
`onThreadRepliesClick`	`(message: CometChat.BaseMessage) => void`	User clicks the thread reply indicator
`onAvatarClick`	`(user: CometChat.User) => void`	User clicks an avatar on an incoming message
`onEditMessage`	`(message: CometChat.BaseMessage) => void`	User selects “Edit” from context menu
`onReplyMessage`	`(message: CometChat.BaseMessage) => void`	User selects “Reply” from context menu
`onReactionClick`	`(reaction: CometChat.ReactionCount, message: CometChat.BaseMessage) => void`	User clicks a reaction count pill
`onReactionListItemClick`	`(reaction: CometChat.Reaction, message: CometChat.BaseMessage) => void`	User clicks an individual reactor in the reaction list
`onActiveChatChanged`	`(data: { user?, group?, message?, unreadMessageCount? }) => void`	Active chat context set on initial load
`onMessageRead`	`(message: CometChat.BaseMessage) => void`	A message is marked as read
`onMessageDeleted`	`(message: CometChat.BaseMessage) => void`	A message is deleted
`onConversationMarkedAsRead`	`(conversation: CometChat.Conversation) => void`	Conversation marked as read
`onConversationUpdated`	`(conversation: CometChat.Conversation) => void`	Conversation updated (e.g., mark-as-unread)
`onError`	`((error: CometChat.CometChatException) => void) \| null`	SDK error occurs

Events Emitted

UI events this component publishes:

Event	Payload	Fires when
`ui:message/read`	`{ message }`	Message marked as read (auto on scroll-to-bottom)
`ui:message/deleted`	`{ message }`	Message deleted by user via context menu
`ui:active-chat/changed`	`{ user?, group?, message?, unreadMessageCount? }`	Active chat context set on initial load
`ui:conversation/read`	`{ conversationId }`	Conversation marked as read (on init or scroll-to-bottom)
`ui:conversation/updated`	`{ conversation }`	Conversation updated (e.g., mark-as-unread)

The “Edit” and “Reply” context menu options publish ui:compose/edit and ui:compose/reply events respectively. These are emitted by the message options system (plugins), not by the MessageList component directly. The MessageComposer subscribes to these events to enter edit/reply mode.

Events Received

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

Event	Payload	Behavior
`ui:message/sent`	`{ message, status }`	Appends sent message (optimistic flow from composer)
`ui:compose/edit`	`{ message, status }`	Updates edited message in the list
`ui:group/member-added`	`{ group, members, messages }`	Appends group action message
`ui:group/member-kicked`	`{ group, user, message }`	Appends group action message
`ui:group/member-banned`	`{ group, user, message }`	Appends group action message
`ui:group/member-unbanned`	`{ group, user, message }`	Appends group action message
`ui:group/member-scope-changed`	`{ group, user, newScope }`	Appends group action message
`ui:group/left`	`{ group }`	Appends group action message
`ui:group/ownership-changed`	`{ group, newOwner, previousOwnerUid }`	Appends group action message
`ui:call/outgoing`	`{ call }`	Appends call message
`ui:call/accepted`	`{ call }`	Appends call message
`ui:call/rejected`	`{ call }`	Appends call message
`ui:call/ended`	`{ call? }`	Appends call message

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, onMessagesDeliveredToAll, onMessagesReadByAll
Edits & deletes: onMessageEdited, onMessageDeleted
Transient: onTransientMessageReceived

Customization

View Props

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

<CometChatMessageList
  user={user}
  headerView={<TypingIndicator />}
  footerView={<SmartRepliesBar />}
  emptyView={<EmptyConversation />}
  loadingView={<MessageSkeleton />}
  errorView={<ErrorBanner />}
  bubbleView={(message, loggedInUser) => <CustomBubble message={message} />}
/>

Slot	Signature	Replaces
`bubbleView`	`(message, loggedInUser) => ReactNode`	Entire bubble rendering for each message
`headerView`	`ReactNode`	Header area above the scroll container
`footerView`	`ReactNode`	Footer area below the scroll container
`loadingView`	`ReactNode`	Loading shimmer
`emptyView`	`ReactNode`	Empty state
`errorView`	`ReactNode`	Error state

headerView

Custom view above the message list.

TypeScript
CSS

import { useState, useEffect } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatMessageList, CometChatButton } from "@cometchat/chat-uikit-react";

function MessageListWithHeader() {
  const [chatUser, setChatUser] = useState<CometChat.User>();

  useEffect(() => {
    CometChat.getUser("uid").then((user) => setChatUser(user));
  }, []);

  return chatUser ? (
    <CometChatMessageList
      user={chatUser}
      headerView={
        <div className="header-view">
          <CometChatButton.Root>
            <CometChatButton.Text>Notes</CometChatButton.Text>
          </CometChatButton.Root>
          <CometChatButton.Root>
            <CometChatButton.Text>Pinned Message</CometChatButton.Text>
          </CometChatButton.Root>
          <CometChatButton.Root>
            <CometChatButton.Text>Saved Links</CometChatButton.Text>
          </CometChatButton.Root>
        </div>
      }
    />
  ) : null;
}

.header-view {
  display: flex;
  width: 100%;
  padding: 3px 16px;
  align-items: flex-start;
  gap: 5px;
  background: #edeafa;
}

.header-view .cometchat-button {
  width: auto;
  height: 32px;
  border-radius: 1000px;
  border: 1px solid #e8e8e8;
  background: #fafafa;
}

.header-view .cometchat-button__text {
  color: #6852d6;
  font: 400 12px/14.4px Roboto;
}

footerView

Custom view below the message list.

TypeScript
CSS

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

function MessageListWithFooter({ chatUser }: { chatUser: CometChat.User }) {
  return (
    <CometChatMessageList
      user={chatUser}
      footerView={
        <div className="footer-view">
          <CometChatButton.Root>
            <CometChatButton.Text>Ice Breakers</CometChatButton.Text>
          </CometChatButton.Root>
          <CometChatButton.Root>
            <CometChatButton.Text>+1-212-456-7890</CometChatButton.Text>
          </CometChatButton.Root>
        </div>
      }
    />
  );
}

.footer-view {
  display: flex;
  width: 100%;
  padding: 3px 16px;
  align-items: flex-start;
  gap: 5px;
  background: #edeafa;
}

Compound Composition

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

<CometChatMessageList.Root user={user}>
  {/* No Header — it won't render */}
  <CometChatMessageList.LoadingState />
  <CometChatMessageList.ErrorState />
  <CometChatMessageList.EmptyState />
  <CometChatMessageList.View />
  <CometChatMessageList.AIFooter />
</CometChatMessageList.Root>

Available sub-components:

Sub-component	Description	Props	Flat API equivalent
`Root`	Context provider, data hook, container	All Root props + `children`	—
`View`	Scrollable message feed	`className`	—
`Header`	Content above the feed	`children`, `className`	`headerView`
`Footer`	Content below the feed	`children`, `className`	`footerView`
`ScrollToBottom`	Floating scroll button	`className`	—
`EmptyState`	Empty state	`children`, `className`	`emptyView`
`ErrorState`	Error state	`children`, `className`	`errorView`
`LoadingState`	Loading shimmer	`children`, `className`	`loadingView`
`DateSeparator`	Day separator	`className`	—
`AIFooter`	Smart replies / starters	`className`	—

CSS Styling

Override design tokens on the component selector:

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

.cometchat-message-list__date-separator {
  --cometchat-text-color-secondary: #aaa;
}

Props

All props are optional (though you must pass either user or group to render messages).

View slot props (bubbleView, headerView, footerView, loadingView, emptyView, errorView) are convenience props available only on the flat API. In compound composition mode, use the corresponding sub-components directly.

Entity

user

The user entity for a 1-on-1 conversation. Mutually exclusive with group.


Type	`CometChat.User`
Default	`undefined`

group

The group entity for a group conversation. Mutually exclusive with user.


Type	`CometChat.Group`
Default	`undefined`

parentMessageId

Enables thread mode. When set, the component fetches and displays replies to the specified parent message instead of the main conversation feed.


Type	`number`
Default	`undefined`

Data

messagesRequestBuilder

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


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

reactionsRequestBuilder

Custom request builder for fetching reactions on messages.


Type	`CometChat.ReactionsRequestBuilder`
Default	`undefined`

messageTypes

Restrict which message types are fetched and displayed.


Type	`string[]`
Default	Plugin registry types

messageCategories

Restrict which message categories are fetched and displayed.


Type	`string[]`
Default	Plugin registry categories

goToMessageId

Jump to a specific message by ID (e.g., from search results or a deep link). The list scrolls to and highlights the target message.


Type	`number`
Default	`undefined`

startFromUnreadMessages

When true, the list scrolls to the first unread message on open instead of the bottom.


Type	`boolean`
Default	`false`

loadLastAgentConversation

When true, loads the last agent conversation on initial render. Used for AI agent chat flows.


Type	`boolean`
Default	`false`

Visibility

hideReceipts

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


Type	`boolean`
Default	`false`

hideStickyDate

Hide the sticky date header that floats at the top of the scroll area.


Type	`boolean`
Default	`false`

hideDateSeparator

Hide date separators between calendar days in the message feed.


Type	`boolean`
Default	`false`

hideAvatar

Hide the avatar on incoming messages in group conversations.


Type	`boolean`
Default	`false`

hideGroupActionMessages

Filter out group action messages (member joined, left, kicked, etc.).


Type	`boolean`
Default	`false`

hideModerationView

Hide the moderation footer beneath disapproved messages.


Type	`boolean`
Default	`false`

showScrollbar

Show the native scrollbar on the message list. When false, the scrollbar is hidden but scrolling still works.


Type	`boolean`
Default	`false`

showSmartReplies

Show AI-generated smart reply suggestions in the footer when the last received message matches keyword criteria.


Type	`boolean`
Default	`false`

showConversationStarters

Show AI-generated conversation starters in the footer when the message list is empty.


Type	`boolean`
Default	`false`

showMarkAsUnreadOption

Show the “Mark as Unread” option in the message context menu.


Type	`boolean`
Default	`false`

disableTruncation

Disable text truncation (read more / show less) in text bubbles. When true, full message text is always shown.


Type	`boolean`
Default	`false`

isAgentChat

Whether this is an AI agent chat. Suppresses moderation UI and enables agent-specific behaviors.


Type	`boolean`
Default	`false`

Option Toggles

hideReplyOption

Hide the “Reply” option from the message context menu.


Type	`boolean`
Default	`false`

hideReplyInThreadOption

Hide the “Reply in Thread” option from the message context menu.


Type	`boolean`
Default	`false`

hideEditMessageOption

Hide the “Edit” option from the message context menu.


Type	`boolean`
Default	`false`

hideDeleteMessageOption

Hide the “Delete” option from the message context menu.


Type	`boolean`
Default	`false`

hideCopyMessageOption

Hide the “Copy” option from the message context menu.


Type	`boolean`
Default	`false`

hideReactionOption

Hide the “React” option from the message context menu.


Type	`boolean`
Default	`false`

hideMessageInfoOption

Hide the “Message Info” option from the message context menu.


Type	`boolean`
Default	`false`

hideFlagMessageOption

Hide the “Flag/Report” option from the message context menu.


Type	`boolean`
Default	`false`

hideMessagePrivatelyOption

Hide the “Message Privately” option from the message context menu.


Type	`boolean`
Default	`false`

hideTranslateMessageOption

Hide the “Translate” option from the message context menu.


Type	`boolean`
Default	`false`

hideFlagRemarkField

Hide the remark textarea in the flag/report message dialog.


Type	`boolean`
Default	`false`

quickOptionsCount

Number of quick-action options shown inline next to the bubble before overflowing into the “More” menu.


Type	`number`
Default	`3`

Date Formatting

separatorDateTimeFormat

Custom date format for in-list day separators (“Today”, “Yesterday”, etc.).


Type	`CometChatDateFormatConfig`
Default	Built-in format

stickyDateTimeFormat

Custom date format for the sticky date header floating above messages.


Type	`CometChatDateFormatConfig`
Default	Built-in format

messageSentAtDateTimeFormat

Custom date format for the timestamp shown beside the message bubble.


Type	`CometChatDateFormatConfig`
Default	Built-in format

messageInfoDateTimeFormat

Custom date format for timestamps in the MessageInformation sheet.


Type	`CometChatDateFormatConfig`
Default	Built-in format

Alignment

messageAlignment

Controls message bubble alignment. 0 aligns all messages to the left. 1 uses standard alignment (sent on right, received on left).


Type	`CometChatMessageListAlignment`
Default	`1` (standard)

Sound

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

AI Features

smartRepliesKeywords

Keywords that trigger smart replies when found in a received text message. If set to an empty array, smart replies show for every received text message.


Type	`string[]`
Default	`['what', 'when', 'why', 'who', 'where', 'how', '?']`

smartRepliesDelayDuration

Delay in milliseconds before showing smart replies after a qualifying message is received. Acts as a debounce — if another message arrives within this window, the timer resets.


Type	`number`
Default	`10000`

Callbacks

onThreadRepliesClick

Callback when the thread reply indicator is clicked on a message bubble.


Type	`(message: CometChat.BaseMessage) => void`
Default	`undefined`

onAvatarClick

Callback when an incoming message avatar is clicked.


Type	`(user: CometChat.User) => void`
Default	`undefined`

onEditMessage

Callback when the “Edit” context menu option is clicked. Typically sets the message in edit mode in the composer.


Type	`(message: CometChat.BaseMessage) => void`
Default	`undefined`

onReplyMessage

Callback when the “Reply” context menu option is clicked. Typically sets the message as reply-to in the composer.


Type	`(message: CometChat.BaseMessage) => void`
Default	`undefined`

onReactionClick

Callback when a reaction count pill is clicked on a message.


Type	`(reaction: CometChat.ReactionCount, message: CometChat.BaseMessage) => void`
Default	`undefined`

onReactionListItemClick

Callback when an individual reactor in the reaction list is clicked.


Type	`(reaction: CometChat.Reaction, message: CometChat.BaseMessage) => void`
Default	`undefined`

onActiveChatChanged

Callback invoked on first load with the active chat context (user/group, last message, unread count).


Type	`(data: { user?, group?, message?, unreadMessageCount? }) => void`
Default	`undefined`

onMessageRead

Callback when a message is marked as read.


Type	`(message: CometChat.BaseMessage) => void`
Default	`undefined`

onMessageDeleted

Callback when a message is deleted.


Type	`(message: CometChat.BaseMessage) => void`
Default	`undefined`

onConversationMarkedAsRead

Callback when the conversation is marked as read.


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

onConversationUpdated

Callback when mark-as-unread succeeds (conversation updated).


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

onError

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


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

View Slots

bubbleView

Replace the entire bubble rendering for each message. When provided, the default plugin-based BubbleRenderer is skipped entirely.


Type	`(message: CometChat.BaseMessage, loggedInUser: CometChat.User) => ReactNode`
Default	`undefined`

<CometChatMessageList
  user={user}
  bubbleView={(message, loggedInUser) => (
    <div className="my-bubble">
      {message.getText?.() || "Custom bubble"}
    </div>
  )}
/>

headerView

Custom content rendered above the scroll container (e.g., typing indicator, pinned message).


Type	`ReactNode`
Default	`undefined`

footerView

Custom content rendered below the scroll container (e.g., smart replies bar).


Type	`ReactNode`
Default	`undefined`

loadingView

Custom loading state shown while messages are being fetched.


Type	`ReactNode`
Default	Built-in shimmer

emptyView

Custom empty state shown when there are no messages in the conversation.


Type	`ReactNode`
Default	Built-in empty state

errorView

Custom error state shown when message fetching fails.


Type	`ReactNode`
Default	Built-in error state

CSS Selectors

Target	Selector
Root container	`.cometchat-message-list`
Header area	`.cometchat-message-list__header`
Footer area	`.cometchat-message-list__footer`
Scroll container	`.cometchat-message-list__scroll-container`
Date separator	`.cometchat-message-list__date-separator`
Floating sticky date	`.cometchat-message-list__floating-date`
New message divider	`.cometchat-message-list__new-message-divider`
Scroll-to-bottom button	`.cometchat-message-list__scroll-to-bottom`
Empty state	`.cometchat-message-list__empty-state`
Error state	`.cometchat-message-list__error-state`
Loading state	`.cometchat-message-list__loading-state`

Next Steps

Message Composer

Add a composer below the message list for sending messages

Thread Header

Display thread context above a threaded message list

Plugins Overview

Learn how plugins register custom bubble renderers

Theming

Customize colors, fonts, and spacing

​Overview

​Usage

​Flat API

​Compound Composition

​Full Layout Example

​Filtering

​Filter Recipes

​Actions and Events

​Callback Props

​Events Emitted

​Events Received

​SDK Listeners (Automatic)

​Customization

​View Props

​headerView

​footerView

​Compound Composition

​CSS Styling

​Props

​Entity

​user

​group

​parentMessageId

​Data

​messagesRequestBuilder

​reactionsRequestBuilder

​messageTypes

​messageCategories

​goToMessageId

​startFromUnreadMessages

​loadLastAgentConversation

​Visibility

​hideReceipts

​hideStickyDate

​hideDateSeparator

​hideAvatar

​hideGroupActionMessages

​hideModerationView

​showScrollbar

​showSmartReplies

​showConversationStarters

​showMarkAsUnreadOption

​disableTruncation

​isAgentChat

​Option Toggles

​hideReplyOption

​hideReplyInThreadOption

​hideEditMessageOption

​hideDeleteMessageOption

​hideCopyMessageOption

​hideReactionOption

​hideMessageInfoOption

​hideFlagMessageOption

​hideMessagePrivatelyOption

​hideTranslateMessageOption

​hideFlagRemarkField

​quickOptionsCount

​Date Formatting

​separatorDateTimeFormat

​stickyDateTimeFormat

​messageSentAtDateTimeFormat

​messageInfoDateTimeFormat

​Alignment

​messageAlignment

​Sound

​disableSoundForMessages

​customSoundForMessages

​AI Features

​smartRepliesKeywords

​smartRepliesDelayDuration

​Callbacks

​onThreadRepliesClick

​onAvatarClick

​onEditMessage

​onReplyMessage

​onReactionClick

​onReactionListItemClick

​onActiveChatChanged

​onMessageRead

​onMessageDeleted

Overview

Usage

Flat API

Compound Composition

Full Layout Example

Filtering

Filter Recipes

Actions and Events

Callback Props

Events Emitted

Events Received

SDK Listeners (Automatic)

Customization

View Props

headerView

footerView

Compound Composition

CSS Styling

Props

Entity

user

group

parentMessageId

Data

messagesRequestBuilder

reactionsRequestBuilder

messageTypes

messageCategories

goToMessageId

startFromUnreadMessages

loadLastAgentConversation

Visibility

hideReceipts

hideStickyDate

hideDateSeparator

hideAvatar

hideGroupActionMessages

hideModerationView

showScrollbar

showSmartReplies

showConversationStarters

showMarkAsUnreadOption

disableTruncation

isAgentChat

Option Toggles

hideReplyOption

hideReplyInThreadOption

hideEditMessageOption

hideDeleteMessageOption

hideCopyMessageOption

hideReactionOption

hideMessageInfoOption

hideFlagMessageOption

hideMessagePrivatelyOption

hideTranslateMessageOption

hideFlagRemarkField

quickOptionsCount

Date Formatting

separatorDateTimeFormat

stickyDateTimeFormat

messageSentAtDateTimeFormat

messageInfoDateTimeFormat

Alignment

messageAlignment

Sound

disableSoundForMessages

customSoundForMessages

AI Features

smartRepliesKeywords

smartRepliesDelayDuration

Callbacks

onThreadRepliesClick

onAvatarClick

onEditMessage

onReplyMessage

onReactionClick

onReactionListItemClick

onActiveChatChanged

onMessageRead

onMessageDeleted