Message List - CometChat Docs

AI Integration Quick Reference

{
  "component": "CometChatMessageList",
  "package": "@cometchat/chat-uikit-react-native",
  "import": "import { CometChatMessageList } from \"@cometchat/chat-uikit-react-native\";",
  "description": "Scrollable list of sent and received messages with text, media, reactions, read receipts, threaded replies, and AI features.",
  "primaryOutput": {
    "prop": "onThreadRepliesPress",
    "type": "(messageObject: CometChat.BaseMessage, messageBubbleView: () => JSX.Element | null) => void"
  },
  "props": {
    "data": {
      "user": { "type": "CometChat.User", "default": "undefined", "note": "User object for 1-on-1 conversation" },
      "group": { "type": "CometChat.Group", "default": "undefined", "note": "Group object for group conversation" },
      "messageRequestBuilder": { "type": "CometChat.MessagesRequestBuilder", "default": "SDK default", "note": "UID/GUID/types/categories are always overridden internally" },
      "templates": { "type": "CometChatMessageTemplate[]", "default": "SDK defaults", "note": "Custom message bubble templates" },
      "addTemplates": { "type": "CometChatMessageTemplate[]", "default": "[]", "note": "Additional message templates to append to defaults" },
      "parentMessageId": { "type": "number", "default": "undefined", "note": "For threaded message view" },
      "goToMessageId": { "type": "string", "default": "undefined", "note": "Message ID to navigate to and highlight" },
      "searchKeyword": { "type": "string", "default": "undefined", "note": "Keyword to highlight in message text" }
    },
    "callbacks": {
      "onThreadRepliesPress": "(messageObject: CometChat.BaseMessage, messageBubbleView: () => JSX.Element | null) => void",
      "onError": "(error: CometChat.CometChatException) => void",
      "onReactionPress": "(reaction: CometChat.ReactionCount, messageObject: CometChat.BaseMessage) => void",
      "onReactionLongPress": "(reaction: CometChat.ReactionCount, messageObject: CometChat.BaseMessage) => void",
      "onReactionListItemPress": "(reaction: CometChat.Reaction, messageObject: CometChat.BaseMessage) => void",
      "onAddReactionPress": "() => void",
      "onSuggestedMessageClick": "(suggestion: string) => void",
      "onLoad": "(messageList: CometChat.BaseMessage[]) => void",
      "onEmpty": "() => void"
    },
    "visibility": {
      "receiptsVisibility": { "type": "boolean", "default": true },
      "avatarVisibility": { "type": "boolean", "default": true },
      "hideError": { "type": "boolean", "default": false },
      "hideTimestamp": { "type": "boolean", "default": false },
      "hideReplyOption": { "type": "boolean", "default": false },
      "hideReplyInThreadOption": { "type": "boolean", "default": false },
      "hideThreadSubscriptionOption": { "type": "boolean", "default": false },
      "hidePinMessageOption": { "type": "boolean", "default": false },
      "hideUnpinMessageOption": { "type": "boolean", "default": false },
      "hideSaveMessageOption": { "type": "boolean", "default": false },
      "hideUnsaveMessageOption": { "type": "boolean", "default": false },
      "hideShareMessageOption": { "type": "boolean", "default": false },
      "hideEditMessageOption": { "type": "boolean", "default": false },
      "hideDeleteMessageOption": { "type": "boolean", "default": false },
      "hideTranslateMessageOption": { "type": "boolean", "default": false },
      "hideReactionOption": { "type": "boolean", "default": false },
      "hideMessagePrivatelyOption": { "type": "boolean", "default": false },
      "hideCopyMessageOption": { "type": "boolean", "default": false },
      "hideMessageInfoOption": { "type": "boolean", "default": false },
      "hideGroupActionMessages": { "type": "boolean", "default": false },
      "hideModerationStatus": { "type": "boolean", "default": false },
      "hideSuggestedMessages": { "type": "boolean", "default": false },
      "showMarkAsUnreadOption": { "type": "boolean", "default": false },
      "hideFlagMessageOption": { "type": "boolean", "default": false },
      "hideFlagRemarkField": { "type": "boolean", "default": false }
    },
    "behavior": {
      "alignment": { "type": "MessageListAlignmentType", "values": ["leftAligned", "standard"], "default": "standard" },
      "scrollToBottomOnNewMessage": { "type": "boolean", "default": false },
      "startFromUnreadMessages": { "type": "boolean", "default": false },
      "loadLastAgentConversation": { "type": "boolean", "default": false, "note": "Loads the most recent existing agent conversation on start" },
      "streamingSpeed": { "type": "number", "default": "undefined", "note": "AI response streaming speed in ms" },
      "enableMultipleAttachments": { "type": "boolean", "default": true, "note": "Enables multi-attachment batch grouping and the plural bubbles (Images/Videos/Audios/Files, Voice Note)" }
    },
    "sound": {
      "disableSoundForMessages": { "type": "boolean", "default": false },
      "customSoundForMessages": { "type": "audio source", "default": "built-in" }
    },
    "ai": {
      "suggestedMessages": { "type": "string[]", "note": "Predefined prompts for AI assistant chats" },
      "aiAssistantTools": { "type": "CometChatAIAssistantTools", "note": "Tool actions for AI assistant" },
      "quickReactionList": { "type": "string[]", "default": "predefined reactions" },
      "streamingSpeed": { "type": "number", "default": "undefined", "note": "AI response streaming speed in ms" }
    },
    "viewSlots": {
      "HeaderView": "({ user, group, id }) => JSX.Element",
      "FooterView": "({ user, group, id }) => JSX.Element",
      "LoadingView": "() => JSX.Element",
      "EmptyView": "() => JSX.Element",
      "ErrorView": "() => JSX.Element",
      "NewMessageIndicatorView": "() => JSX.Element",
      "emptyChatGreetingView": "JSX.Element",
      "emptyChatIntroMessageView": "JSX.Element",
      "emptyChatImageView": "JSX.Element"
    },
    "newMessageIndicator": {
      "newMessageIndicatorStyle": { "type": "NewMessageIndicatorStyle", "default": "built-in" },
      "newMessageIndicatorText": { "type": "string", "default": "built-in" }
    },
    "formatting": {
      "textFormatters": { "type": "CometChatTextFormatter[]", "default": "default formatters from data source" },
      "datePattern": "(message: CometChat.BaseMessage) => string",
      "dateSeperatorPattern": "(date: number) => string"
    }
  },
  "events": [
    { "name": "openChat", "payload": "{ user, group }", "description": "User opens a chat" },
    { "name": "ccMessageEdited", "payload": "{ message }", "description": "Message edited by logged-in user" },
    { "name": "ccMessageDeleted", "payload": "{ message }", "description": "Message deleted by logged-in user" },
    { "name": "ccActiveChatChanged", "payload": "chat details", "description": "User navigates to a different chat" },
    { "name": "ccMessageRead", "payload": "{ message }", "description": "Message read by logged-in user" },
    { "name": "ccMessageDelivered", "payload": "{ message }", "description": "Messages marked as delivered" }
  ],
  "sdkListeners": [
    "onTextMessageReceived", "onMediaMessageReceived", "onCustomMessageReceived",
    "onMessageEdited", "onMessageDeleted", "onTypingStarted", "onTypingEnded",
    "onMessagesDelivered", "onMessagesRead"
  ],
  "compositionExample": {
    "description": "Message list wired with header and composer for complete chat view",
    "components": ["CometChatMessageHeader", "CometChatMessageList", "CometChatMessageComposer"],
    "flow": "Pass user or group prop to all three components for a complete messaging interface"
  },
  "types": {
    "MessageListAlignmentType": { "leftAligned": "All messages aligned to left", "standard": "Sent messages right, received messages left" }
  }
}

Where It Fits

CometChatMessageList renders a scrollable, real-time message feed for a user or group conversation. Wire it alongside CometChatMessageHeader and CometChatMessageComposer to build a standard chat view.

import { useState, useEffect } from "react";
import { View, StyleSheet } from "react-native";
import { GestureHandlerRootView } from "react-native-gesture-handler";
import { SafeAreaProvider } from "react-native-safe-area-context";
import {
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
  CometChatThemeProvider,
} from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

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

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

  return chatUser ? (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <SafeAreaProvider>
        <CometChatThemeProvider>
          <View style={styles.container}>
            <CometChatMessageHeader user={chatUser} />
            <CometChatMessageList user={chatUser} />
            <CometChatMessageComposer user={chatUser} />
          </View>
        </CometChatThemeProvider>
      </SafeAreaProvider>
    </GestureHandlerRootView>
  ) : null;
}

const styles = StyleSheet.create({
  container: { flex: 1 },
});

Minimal Render

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

function MessageListDemo() {
  return <CometChatMessageList user={chatUser} />;
}

export default MessageListDemo;

Simply adding the CometChatMessageList component to the layout will result in an error. To fetch messages, you need to supplement it with user or group prop.

Multi-Attachment Batch Grouping

When several attachments are sent together from the composer’s staging tray, they arrive as multiple media messages — one per media kind, in the fixed order Images → Videos → Audios → Files — that all share a single batchId in their metadata. The message list detects consecutive messages carrying the same batchId from the same sender and renders them as one visually connected group instead of separate, independently-chromed bubbles.

Grouped chrome

Within a batch, the list renders shared chrome so the group reads as one logical message:

The avatar and sender name render once, on the first message of the batch.
Delivery/read receipts render once, on the last message of the batch.
Interior spacing collapses so the bubbles sit tightly, reading as a single stack.
The caption (if any) is carried by the last message of the batch.

This is computed automatically — you don’t configure anything, and ordinary consecutive messages (without a batchId) are unaffected.

What renders inside a batch

Each message in the batch is single-kind, so it renders the matching plural bubble — an image/video grid, a stacked audio-player list, or a connected file-card stack (see Message Bubble Styling). Recorded voice notes are never batched with files — they render their own voice-note bubble. Set enableMultipleAttachments to false (together with the same prop on the composer) to disable multi-attachment rendering.

Filtering Messages

Pass a CometChat.MessagesRequestBuilder to messageRequestBuilder. The UID/GUID parameters are always overridden internally based on the user/group prop.

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

function FilteredMessageList() {
  return (
    <CometChatMessageList
      user={chatUser}
      messageRequestBuilder={
        new CometChat.MessagesRequestBuilder().setLimit(5)
      }
    />
  );
}

The following parameters in messageRequestBuilder will always be altered inside the message list:

UID
GUID
types
categories

Refer to MessagesRequestBuilder for the full builder API.

Actions and Events

Callback Props

onThreadRepliesPress

Fires when you press on the threaded message bubble.

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

function MessageListWithThreads() {
  const handleThreadReplies = (
    msg: CometChat.BaseMessage,
    messageBubbleView: () => JSX.Element | null
  ) => {
    console.log("Thread replies pressed:", msg.getId());
  };

  return (
    <CometChatMessageList
      user={chatUser}
      onThreadRepliesPress={handleThreadReplies}
    />
  );
}

onError

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

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

function MessageListWithErrorHandler() {
  return (
    <CometChatMessageList
      user={chatUser}
      onError={(error: CometChat.CometChatException) => {
        console.error("MessageList error:", error);
      }}
    />
  );
}

onReactionPress

Fires when a reaction on a message bubble is clicked.

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

function MessageListWithReactions() {
  const handleReactionPress = (
    reaction: CometChat.ReactionCount,
    messageObject: CometChat.BaseMessage
  ) => {
    console.log("Reaction pressed:", reaction, messageObject.getId());
  };

  return (
    <CometChatMessageList
      user={chatUser}
      onReactionPress={handleReactionPress}
    />
  );
}

onLoad

Fires when messages are successfully fetched and loaded.

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

function MessageListWithLoadHandler() {
  const handleLoad = (messageList: CometChat.BaseMessage[]) => {
    console.log("Messages loaded:", messageList.length);
  };

  return <CometChatMessageList user={chatUser} 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
`openChat`	User opens a user or group chat	`{ user, group }`
`ccMessageEdited`	Message edited by logged-in user	`{ message }`
`ccMessageDeleted`	Message deleted by logged-in user	`{ message }`
`ccActiveChatChanged`	User navigates to a different chat	`chat details`
`ccMessageRead`	Message read by logged-in user	`{ message }`
`ccMessageDelivered`	Messages marked as delivered	`{ message }`

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

function useMessageListEvents() {
  useEffect(() => {
    const uiListenerId = "UI_LISTENER_" + Date.now();
    const messageListenerId = "MESSAGE_LISTENER_" + Date.now();

    CometChatUIEventHandler.addUIListener(uiListenerId, {
      openChat: ({ user, group }) => {
        console.log("Chat opened:", user || group);
      },
    });

    CometChatUIEventHandler.addMessageListener(messageListenerId, {
      ccMessageEdited: ({ message }) => {
        console.log("Message edited:", message.getId());
      },
      ccMessageDeleted: ({ message }) => {
        console.log("Message deleted:", message.getId());
      },
    });

    return () => {
      CometChatUIEventHandler.removeUIListener(uiListenerId);
      CometChatUIEventHandler.removeMessageListener(messageListenerId);
    };
  }, []);
}

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`	Appends new message to list
`onMessageEdited` / `onMessageDeleted`	Updates/removes message in list
`onTypingStarted` / `onTypingEnded`	Shows/hides typing indicator
`onMessagesDelivered` / `onMessagesRead`	Updates receipt ticks

Pin, Save and Thread Subscription Options

These actions appear in the message options sheet, each with a prop to hide it.

Prop	Default	Hides
`hidePinMessageOption`	`false`	Pin message
`hideUnpinMessageOption`	`false`	Unpin message
`hideSaveMessageOption`	`false`	Save message
`hideUnsaveMessageOption`	`false`	Unsave message
`hideThreadSubscriptionOption`	`false`	Follow / Unfollow thread

A false default does not mean the option is visible. Pin, Save and Pin Conversation are also gated on your app’s CometChat Dashboard settings. The UI Kit resolves those flags at login and on every reconnect, so an option renders only when the Dashboard allows it and the prop does not hide it. There is no start-up call to make.Thread subscription is different: it is not an app setting, so ThreadSubscriptionConfig is a real switch — and it defaults to on, matching the React UI Kit. The option shows unless you opt out.

TypeScript
JavaScript

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

// Thread subscription is on by default — call this only to opt OUT.
// Pin and Save need no equivalent: the kit reads their Dashboard flags at login.
ThreadSubscriptionConfig.setEnabled(false);

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

ThreadSubscriptionConfig.setEnabled(false);

The Dashboard flag and the per-instance prop are ANDed: the Dashboard decides whether a feature is available to your app at all, and these props hide it on one particular list.

Removing asks, adding does not. Unpin and Unsave show a confirmation; Pin and Save run immediately. The asymmetry is deliberate and shared across all CometChat UI Kits — the additive action has its own undo one tap away, the destructive one does not.

A just-sent message may briefly refuse to pin or save. On a moderated app the server holds a new message at moderation.status: "pending" for a second or two and refuses with 403 ERR_MESSAGE_NO_ACCESS — the same code it returns for a genuine permission refusal. The kit keeps the options visible and shows a transient message rather than claiming the user lacks permission, because by the time someone opens the sheet and taps, moderation has usually finished.

See Pinned Messages and Saved Messages for the panels that list the results.

Custom View Slots

Each slot replaces a section of the default UI.

Slot	Signature	Replaces
`HeaderView`	`({ user, group, id }) => JSX.Element`	Area above the message list
`FooterView`	`({ user, group, id }) => JSX.Element`	Area below the message list
`LoadingView`	`() => JSX.Element`	Loading state
`EmptyView`	`() => JSX.Element`	Empty state
`ErrorView`	`() => JSX.Element`	Error state
`NewMessageIndicatorView`	`() => JSX.Element`	New messages indicator
`templates`	`CometChatMessageTemplate[]`	Message bubble rendering
`textFormatters`	`CometChatTextFormatter[]`	Text formatting in messages

HeaderView

Custom view above the message list.

import { CometChatMessageList } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { View, Text, TouchableOpacity } from "react-native";

function MessageListWithHeader() {
  const getHeaderView = ({
    user,
    group,
    id,
  }: {
    user?: CometChat.User;
    group?: CometChat.Group;
    id?: { uid?: string; guid?: string; parentMessageId?: string };
  }) => {
    return (
      <View style={{ flexDirection: "row", padding: 10, backgroundColor: "#edeafa", gap: 8 }}>
        <TouchableOpacity style={{ backgroundColor: "#fafafa", paddingHorizontal: 12, paddingVertical: 6, borderRadius: 16 }}>
          <Text style={{ color: "#6852D6" }}>Notes</Text>
        </TouchableOpacity>
        <TouchableOpacity style={{ backgroundColor: "#fafafa", paddingHorizontal: 12, paddingVertical: 6, borderRadius: 16 }}>
          <Text style={{ color: "#6852D6" }}>Pinned</Text>
        </TouchableOpacity>
      </View>
    );
  };

  return <CometChatMessageList user={chatUser} HeaderView={getHeaderView} />;
}

FooterView

Custom view below the message list.

import { CometChatMessageList } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { View, Text, TouchableOpacity } from "react-native";

function MessageListWithFooter() {
  const getFooterView = ({
    user,
    group,
    id,
  }: {
    user?: CometChat.User;
    group?: CometChat.Group;
    id?: { uid?: string; guid?: string; parentMessageId?: string };
  }) => {
    return (
      <View style={{ flexDirection: "row", padding: 10, backgroundColor: "#edeafa", gap: 8 }}>
        <TouchableOpacity style={{ backgroundColor: "#fafafa", paddingHorizontal: 12, paddingVertical: 6, borderRadius: 16 }}>
          <Text style={{ color: "#6852D6" }}>Ice Breakers</Text>
        </TouchableOpacity>
      </View>
    );
  };

  return <CometChatMessageList user={chatUser} FooterView={getFooterView} />;
}

templates

Custom message bubble templates via CometChatMessageTemplate.

import { CometChatMessageList, ChatConfigurator, CometChatMessageTemplate } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { Text } from "react-native";

function MessageListCustomTemplates() {
  const getTemplates = () => {
    let templates: CometChatMessageTemplate[] = ChatConfigurator.getDataSource().getAllMessageTemplates(theme);
    templates.map((data) => {
      if (data.type === "text") {
        data.ContentView = (messageObject: CometChat.BaseMessage) => {
          const textMessage = messageObject as CometChat.TextMessage;
          return (
            <Text style={{ backgroundColor: "#fff5fd", padding: 10 }}>
              {textMessage.getText()}
            </Text>
          );
        };
      }
    });
    return templates;
  };

  return <CometChatMessageList user={chatUser} templates={getTemplates()} />;
}

dateSeperatorPattern

Custom format for displaying sticky date separators.

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

function MessageListCustomDateSeparator() {
  const customDateSeparatorPattern = (date: number) => {
    const timeStampInSeconds = new Date(date * 1000);
    const day = String(timeStampInSeconds.getUTCDate()).padStart(2, "0");
    const month = String(timeStampInSeconds.getUTCMonth() + 1).padStart(2, "0");
    const year = timeStampInSeconds.getUTCFullYear();
    return `${day}/${month}/${year}`;
  };

  return (
    <CometChatMessageList
      user={chatUser}
      dateSeperatorPattern={customDateSeparatorPattern}
    />
  );
}

datePattern

Custom format for message timestamps.

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

function MessageListCustomDatePattern() {
  const generateDateString = (message: CometChat.BaseMessage) => {
    const days = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
    const timeStamp = message.getSentAt();
    if (timeStamp) {
      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 "---, --:--";
  };

  return (
    <CometChatMessageList
      user={chatUser}
      datePattern={generateDateString}
    />
  );
}

textFormatters

Custom text formatters for message content.

import {
  CometChatMessageList,
  CometChatTextFormatter,
  CometChatMentionsFormatter,
} from "@cometchat/chat-uikit-react-native";

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

  return (
    <CometChatMessageList
      user={chatUser}
      textFormatters={getTextFormatters()}
    />
  );
}

See CometChatMentionsFormatter for mention formatting.

Common Patterns

Threaded message list

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

function ThreadedMessageList() {
  return (
    <CometChatMessageList
      user={chatUser}
      parentMessageId={parentMessage.getId()}
    />
  );
}

Hide all chrome — minimal list

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

function MinimalMessageList() {
  return (
    <CometChatMessageList
      user={chatUser}
      receiptsVisibility={false}
      avatarVisibility={false}
      hideTimestamp={true}
      hideGroupActionMessages={true}
    />
  );
}

Left-aligned messages

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

function LeftAlignedList() {
  return (
    <CometChatMessageList
      user={chatUser}
      alignment="leftAligned"
    />
  );
}

AI conversation starters

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

function AIMessageList() {
  const suggestedMessages = [
    "How can I help you today?",
    "Tell me more about your issue.",
    "What would you like to achieve?",
  ];

  return (
    <CometChatMessageList
      user={chatUser}
      suggestedMessages={suggestedMessages}
      onSuggestedMessageClick={(suggestion) => console.log("Clicked:", suggestion)}
    />
  );
}

Navigate to specific message

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

function NavigateToMessage() {
  return (
    <CometChatMessageList
      user={chatUser}
      goToMessageId="message_id_123"
    />
  );
}

Load last agent conversation

Resume the most recent AI agent conversation on start:

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

function AgentChat() {
  return (
    <CometChatMessageList
      user={agentUser}
      loadLastAgentConversation={true}
    />
  );
}

Styling

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

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

function StyledMessageList() {
  return (
    <CometChatMessageList
      user={chatUser}
      style={{
        containerStyle: {
          backgroundColor: "#FEEDE1",
        },
        outgoingMessageBubbleStyles: {
          containerStyle: {
            backgroundColor: "#F76808",
          },
        },
      }}
    />
  );
}

Style Properties

Property	Type	Description
`containerStyle`	`ViewStyle`	Style for the root container
`incomingMessageBubbleStyles`	`object`	Style for incoming message bubbles
`outgoingMessageBubbleStyles`	`object`	Style for outgoing message bubbles
`dateSeparatorStyle`	`object`	Style for date separators
`actionSheetStyle`	`object`	Style for the action sheet

Props

All props are optional unless noted. Either user or group is required.

alignment

Controls message alignment.


Type	`"leftAligned" \| "standard"`
Default	`"standard"`

avatarVisibility

Shows/hides avatars on messages.


Type	`boolean`
Default	`true`

enableMultipleAttachments

Enables multi-attachment rendering: batch grouping and the plural bubbles (Images/Videos/Audios/Files, Voice Note). Set false (with the matching composer prop) for legacy single-attachment rendering.


Type	`boolean`
Default	`true`

customSoundForMessages

Custom sound file for incoming message notifications.


Type	`audio source`
Default	Built-in sound

datePattern

Custom function to format message timestamps.


Type	`(message: CometChat.BaseMessage) => string`
Default	Component default

dateSeperatorPattern

Custom function to format date separator timestamps.


Type	`(date: number) => string`
Default	Component default

disableSoundForMessages

Disables the notification sound for incoming messages.


Type	`boolean`
Default	`false`

EmptyView

Custom component displayed when there are no messages.


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

ErrorView

Custom component displayed when an error occurs.


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

FooterView

Custom component displayed below the message list.


Type	`({ user, group, id }) => JSX.Element`
Default	`undefined`

goToMessageId

Scrolls to the specified message on initial load.


Type	`string`
Default	`undefined`

group

The group for group conversation messages.


Type	`CometChat.Group`
Default	`undefined`

HeaderView

Custom component displayed above the message list.


Type	`({ user, group, id }) => JSX.Element`
Default	`undefined`

hideCopyMessageOption

Hides the copy message option.


Type	`boolean`
Default	`false`

hideDeleteMessageOption

Hides the delete message option.


Type	`boolean`
Default	`false`

hideEditMessageOption

Hides the edit message option.


Type	`boolean`
Default	`false`

hideError

Hides the error state view.


Type	`boolean`
Default	`false`

hideFlagMessageOption

Hides the “Report Message” option.


Type	`boolean`
Default	`false`

hideFlagRemarkField

Hides the remark text area in the flag message dialog.


Type	`boolean`
Default	`false`

hideGroupActionMessages

Hides group action messages (join, leave, kick, etc.).


Type	`boolean`
Default	`false`

hideMessageInfoOption

Hides the message info option.


Type	`boolean`
Default	`false`

hideMessagePrivatelyOption

Hides the “Message Privately” option.


Type	`boolean`
Default	`false`

hideModerationStatus

Hides the moderation status UI.


Type	`boolean`
Default	`false`

hidePinMessageOption

Hides the “Pin message” option. Pin Messages must also be enabled for your app in the CometChat Dashboard before the option can appear at all.


Type	`boolean`
Default	`false`

hideReactionOption

Hides the reaction option.


Type	`boolean`
Default	`false`

hideReplyInThreadOption

Hides the “Reply in Thread” option.


Type	`boolean`
Default	`false`

hideReplyOption

Hides the reply option.


Type	`boolean`
Default	`false`

hideSaveMessageOption

Hides the “Save message” option. Save Messages must also be enabled for your app in the CometChat Dashboard before the option can appear at all.


Type	`boolean`
Default	`false`

hideShareMessageOption

Hides the share message option.


Type	`boolean`
Default	`false`

hideSuggestedMessages

Hides suggested messages in AI view.


Type	`boolean`
Default	`false`

hideThreadSubscriptionOption

Hides the “Follow / Unfollow thread” option. Unlike pin and save, ThreadSubscriptionConfig defaults to on, so this prop is the usual way to hide it.


Type	`boolean`
Default	`false`

hideTimestamp

Hides timestamps on messages.


Type	`boolean`
Default	`false`

hideUnpinMessageOption

Hides the “Unpin message” option.


Type	`boolean`
Default	`false`

hideUnsaveMessageOption

Hides the “Unsave message” option.


Type	`boolean`
Default	`false`

hideTranslateMessageOption

Hides the translate message option.


Type	`boolean`
Default	`false`

loadLastAgentConversation

Automatically loads the most recent agent conversation when set to true.


Type	`boolean`
Default	`false`

LoadingView

Custom component displayed during the loading state.


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

messageRequestBuilder

Controls which messages load and in what order.


Type	`CometChat.MessagesRequestBuilder`
Default	SDK default

UID/GUID are always overridden internally.

NewMessageIndicatorView

Custom view for the “New Messages” indicator.


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

onAddReactionPress

Callback fired when the “Add More Reactions” button is clicked.


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

onEmpty

Callback fired when the message list is empty.


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

onError

Callback fired when the component encounters an error.


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

onLoad

Callback fired when messages are loaded.


Type	`(messageList: CometChat.BaseMessage[]) => void`
Default	`undefined`

onReactionLongPress

Callback fired when a reaction is long-pressed.


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

onReactionPress

Callback fired when a reaction is clicked.


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

onSuggestedMessageClick

Callback fired when a suggested message is clicked.


Type	`(suggestion: string) => void`
Default	`undefined`

onThreadRepliesPress

Callback fired when a threaded message reply count is clicked.


Type	`(messageObject: CometChat.BaseMessage, messageBubbleView: () => JSX.Element \| null) => void`
Default	`undefined`

parentMessageId

Displays threaded conversation for the specified parent message.


Type	`number`
Default	`undefined`

quickReactionList

Custom list of quick reactions.


Type	`string[]`
Default	Predefined reactions

receiptsVisibility

Shows/hides read/delivery receipt indicators.


Type	`boolean`
Default	`true`

scrollToBottomOnNewMessage

Auto-scrolls to bottom when new messages arrive.


Type	`boolean`
Default	`false`

searchKeyword

Keyword to highlight in message text.


Type	`string`
Default	`undefined`

showMarkAsUnreadOption

Shows “Mark Unread” option in message actions.


Type	`boolean`
Default	`false`

startFromUnreadMessages

Loads from the first unread message if available.


Type	`boolean`
Default	`false`

suggestedMessages

Predefined prompts for AI assistant chats.


Type	`string[]`
Default	`undefined`

templates

Custom message bubble templates. Replaces all default templates.


Type	`CometChatMessageTemplate[]`
Default	SDK defaults

addTemplates

Additional message templates to append to the default templates.


Type	`CometChatMessageTemplate[]`
Default	`[]`

newMessageIndicatorStyle

Custom styles for the “New Messages” indicator.


Type	`NewMessageIndicatorStyle`
Default	Built-in style

newMessageIndicatorText

Custom text for the “New Messages” indicator.


Type	`string`
Default	Built-in text

streamingSpeed

Speed in milliseconds for AI response streaming animation.


Type	`number`
Default	`undefined`

aiAssistantTools

Tool actions for AI assistant functionality.


Type	`CometChatAIAssistantTools`
Default	`undefined`

textFormatters

Custom text formatters for message content.


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

user

The user for 1-on-1 conversation messages.


Type	`CometChat.User`
Default	`undefined`

Next Steps

Message Header

Display user or group details in the chat toolbar

Message Composer

Compose and send messages in a chat

Messages

Complete messaging interface with header, list, and composer

Component Styling

Customize the appearance of UI Kit components

​Where It Fits

​Minimal Render

​Multi-Attachment Batch Grouping

​Grouped chrome

​What renders inside a batch

​Filtering Messages

​Actions and Events

​Callback Props

​onThreadRepliesPress

​onError

​onReactionPress

​onLoad

​Global UI Events

​SDK Events (Real-Time, Automatic)

​Pin, Save and Thread Subscription Options

​Custom View Slots

​HeaderView

​FooterView

​templates

​dateSeperatorPattern

​datePattern

​textFormatters

​Common Patterns

​Threaded message list

​Hide all chrome — minimal list

​Left-aligned messages

​AI conversation starters

​Navigate to specific message

​Load last agent conversation

​Styling

​Style Properties

​Props

​alignment

​avatarVisibility

​enableMultipleAttachments

​customSoundForMessages

​datePattern

​dateSeperatorPattern

​disableSoundForMessages

​EmptyView

​ErrorView

​FooterView

​goToMessageId

​group

​HeaderView

​hideCopyMessageOption

​hideDeleteMessageOption

​hideEditMessageOption

​hideError

​hideFlagMessageOption

​hideFlagRemarkField

​hideGroupActionMessages

​hideMessageInfoOption

​hideMessagePrivatelyOption

​hideModerationStatus

​hidePinMessageOption

​hideReactionOption

​hideReplyInThreadOption

​hideReplyOption

​hideSaveMessageOption

​hideShareMessageOption

​hideSuggestedMessages

​hideThreadSubscriptionOption

​hideTimestamp

​hideUnpinMessageOption

​hideUnsaveMessageOption

​hideTranslateMessageOption

​loadLastAgentConversation

​LoadingView

​messageRequestBuilder

​NewMessageIndicatorView

​onAddReactionPress

​onEmpty

​onError

​onLoad

​onReactionLongPress

​onReactionPress

​onSuggestedMessageClick

​onThreadRepliesPress

​parentMessageId

Where It Fits

Minimal Render

Multi-Attachment Batch Grouping

Grouped chrome

What renders inside a batch

Filtering Messages

Actions and Events

Callback Props

onThreadRepliesPress

onError

onReactionPress

onLoad

Global UI Events

SDK Events (Real-Time, Automatic)

Pin, Save and Thread Subscription Options

Custom View Slots

HeaderView

FooterView

templates

dateSeperatorPattern

datePattern

textFormatters

Common Patterns

Threaded message list

Hide all chrome — minimal list

Left-aligned messages

AI conversation starters

Navigate to specific message

Load last agent conversation

Styling

Style Properties

Props

alignment

avatarVisibility

enableMultipleAttachments

customSoundForMessages

datePattern

dateSeperatorPattern

disableSoundForMessages

EmptyView

ErrorView

FooterView

goToMessageId

group

HeaderView

hideCopyMessageOption

hideDeleteMessageOption

hideEditMessageOption

hideError

hideFlagMessageOption

hideFlagRemarkField

hideGroupActionMessages

hideMessageInfoOption

hideMessagePrivatelyOption

hideModerationStatus

hidePinMessageOption

hideReactionOption

hideReplyInThreadOption

hideReplyOption

hideSaveMessageOption

hideShareMessageOption

hideSuggestedMessages

hideThreadSubscriptionOption

hideTimestamp

hideUnpinMessageOption

hideUnsaveMessageOption

hideTranslateMessageOption

loadLastAgentConversation

LoadingView

messageRequestBuilder

NewMessageIndicatorView

onAddReactionPress

onEmpty

onError

onLoad

onReactionLongPress

onReactionPress

onSuggestedMessageClick

onThreadRepliesPress

parentMessageId