> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-chore-codeowners-swapnil-to-jitvar.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Message List

> Display sent and received messages with text, media, reactions, read receipts, threaded replies, and AI features.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "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" }
    }
  }
  ```
</Accordion>

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

```tsx lines theme={null}
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 },
});
```

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-chore-codeowners-swapnil-to-jitvar/3K5qR9gZwpEAh6Sk/images/7c6476ad-message_list-f571abbea715b343416ff5ca1cbc8c9b.png?fit=max&auto=format&n=3K5qR9gZwpEAh6Sk&q=85&s=bd8db6a83b9a0229bccfae0455ae6a20" width="1280" height="800" data-path="images/7c6476ad-message_list-f571abbea715b343416ff5ca1cbc8c9b.png" />
</Frame>

***

## Minimal Render

```tsx lines theme={null}
import { CometChatMessageList } from "@cometchat/chat-uikit-react-native";

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

export default MessageListDemo;
```

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

***

## Multi-Attachment Batch Grouping

When several attachments are sent together from the [composer's staging tray](/ui-kit/react-native/message-composer#multi-attachment-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](/ui-kit/react-native/message-bubble-styling)). Recorded voice notes are never batched with files — they render their own voice-note bubble.

Set [`enableMultipleAttachments`](#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.

```tsx lines theme={null}
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)
      }
    />
  );
}
```

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

  1. UID
  2. GUID
  3. types
  4. categories
</Note>

Refer to [MessagesRequestBuilder](/sdk/react-native/additional-message-filtering) for the full builder API.

***

## Actions and Events

### Callback Props

#### onThreadRepliesPress

Fires when you press on the threaded message bubble.

```tsx lines theme={null}
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).

```tsx lines theme={null}
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.

```tsx lines theme={null}
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.

```tsx lines theme={null}
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 }`     |

```tsx lines theme={null}
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 |

<Warning>
  **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.
</Warning>

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    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);
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    import { ThreadSubscriptionConfig } from "@cometchat/chat-uikit-react-native";

    ThreadSubscriptionConfig.setEnabled(false);
    ```
  </Tab>
</Tabs>

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.

<Note>
  **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.
</Note>

<Note>
  **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.
</Note>

See [Pinned Messages](/ui-kit/react-native/pinned-messages) and
[Saved Messages](/ui-kit/react-native/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.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-chore-codeowners-swapnil-to-jitvar/OUW6oKbzFKyTY_2r/images/ce4ca595-message_list_header_veiw-886f367b48234ddad6bdff6871a7d5fb.png?fit=max&auto=format&n=OUW6oKbzFKyTY_2r&q=85&s=54d41a0205246b4500894ab8eec46306" width="1280" height="800" data-path="images/ce4ca595-message_list_header_veiw-886f367b48234ddad6bdff6871a7d5fb.png" />
</Frame>

```tsx lines theme={null}
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.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-chore-codeowners-swapnil-to-jitvar/dO7mYGlmnN4b9wsx/images/53d4119c-message_list_footer_view-7210ad9b52c7d141691091518bd6e4e3.png?fit=max&auto=format&n=dO7mYGlmnN4b9wsx&q=85&s=399dc8a7948cc8c04b35c96d5c90fef8" width="1280" height="800" data-path="images/53d4119c-message_list_footer_view-7210ad9b52c7d141691091518bd6e4e3.png" />
</Frame>

```tsx lines theme={null}
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.

```tsx lines theme={null}
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.

```tsx lines theme={null}
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.

```tsx lines theme={null}
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.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-chore-codeowners-swapnil-to-jitvar/dQmaIdOgorxWurRm/images/e2732868-mentions_message_bubble-fccf9cbdd63a54c2f734803e4480418a.png?fit=max&auto=format&n=dQmaIdOgorxWurRm&q=85&s=290681f1e847cd27f3d9794713b7f7e9" width="1280" height="800" data-path="images/e2732868-mentions_message_bubble-fccf9cbdd63a54c2f734803e4480418a.png" />
</Frame>

```tsx lines theme={null}
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](/ui-kit/react-native/mentions-formatter-guide) for mention formatting.

***

## Common Patterns

### Threaded message list

```tsx lines theme={null}
import { CometChatMessageList } from "@cometchat/chat-uikit-react-native";

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

### Hide all chrome — minimal list

```tsx lines theme={null}
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

```tsx lines theme={null}
import { CometChatMessageList } from "@cometchat/chat-uikit-react-native";

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

### AI conversation starters

```tsx lines theme={null}
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

```tsx lines theme={null}
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:

```tsx lines theme={null}
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.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-chore-codeowners-swapnil-to-jitvar/SmhtFiUEpsXP3yom/images/03a08ce8-message_list_styling-ebbb6bea74da1c21078f037fb50d8bff.png?fit=max&auto=format&n=SmhtFiUEpsXP3yom&q=85&s=e8e9a898f9a3e19150530ba012ac53f9" width="1280" height="800" data-path="images/03a08ce8-message_list_styling-ebbb6bea74da1c21078f037fb50d8bff.png" />
</Frame>

```tsx lines theme={null}
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](#multi-attachment-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

<CardGroup cols={2}>
  <Card title="Message Header" icon="heading" href="/ui-kit/react-native/message-header">
    Display user or group details in the chat toolbar
  </Card>

  <Card title="Message Composer" icon="pen" href="/ui-kit/react-native/message-composer">
    Compose and send messages in a chat
  </Card>

  <Card title="Messages" icon="comments" href="/ui-kit/react-native/message-list">
    Complete messaging interface with header, list, and composer
  </Card>

  <Card title="Component Styling" icon="paintbrush" href="/ui-kit/react-native/component-styling">
    Customize the appearance of UI Kit components
  </Card>
</CardGroup>