Message List - CometChat Docs

The CometChatMessageList component displays a scrollable list of messages in a conversation. It supports text messages, media messages, reactions, threads, and real-time updates for new messages, edits, and deletions.

CometChatMessageList showing a scrollable list of chat messages with text bubbles, timestamps, and read receipts in a conversation view

AI Integration Quick Reference

{
  "component": "CometChatMessageList",
  "package": "CometChatUIKitSwift",
  "import": "import CometChatUIKitSwift\nimport CometChatSDK",
  "description": "Displays a scrollable list of messages in a conversation with real-time updates for new messages, edits, deletions, reactions, and typing indicators.",
  "inherits": "UIViewController",
  "primaryOutput": {
    "callback": "onMessageClick",
    "type": "(BaseMessage) -> Void"
  },
  "props": {
    "data": {
      "messagesRequestBuilder": {
        "type": "MessagesRequest.MessageRequestBuilder?",
        "default": "nil",
        "note": "Custom request builder for filtering messages"
      },
      "reactionsRequestBuilder": {
        "type": "ReactionsRequest.ReactionsRequestBuilder?",
        "default": "nil",
        "note": "Custom request builder for fetching reactions"
      }
    },
    "callbacks": {
      "onThreadRepliesClick": "(BaseMessage, MessageTemplate) -> Void",
      "onReactionClick": "(ReactionCount, BaseMessage?) -> Void",
      "onReactionListItemClick": "(MessageReaction, BaseMessage) -> Void",
      "onError": "(CometChatException) -> Void",
      "onEmpty": "() -> Void",
      "onLoad": "([BaseMessage]) -> Void"
    },
    "visibility": {
      "hideAvatar": { "type": "Bool", "default": false },
      "hideReceipts": { "type": "Bool", "default": false },
      "hideDateSeparator": { "type": "Bool", "default": false },
      "hideHeaderView": { "type": "Bool", "default": false },
      "hideFooterView": { "type": "Bool", "default": false },
      "hideReactionOption": { "type": "Bool", "default": false },
      "hideReplyInThreadOption": { "type": "Bool", "default": false },
      "hideEditMessageOption": { "type": "Bool", "default": false },
      "hideDeleteMessageOption": { "type": "Bool", "default": false },
      "hideCopyMessageOption": { "type": "Bool", "default": false },
      "hideMessageInfoOption": { "type": "Bool", "default": false },
      "hideTranslateMessageOption": { "type": "Bool", "default": false },
      "hideMessagePrivatelyOption": { "type": "Bool", "default": false },
      "hideGroupActionMessages": { "type": "Bool", "default": false },
      "hideNewMessageIndicator": { "type": "Bool", "default": false },
      "hideEmptyView": { "type": "Bool", "default": false },
      "hideErrorView": { "type": "Bool", "default": false },
      "hideLoadingView": { "type": "Bool", "default": false }
    },
    "sound": {
      "disableSoundForMessages": { "type": "Bool", "default": false }
    },
    "behavior": {
      "scrollToBottomOnNewMessages": { "type": "Bool", "default": true },
      "startFromUnreadMessages": { "type": "Bool", "default": false },
      "showMarkAsUnreadOption": { "type": "Bool", "default": false },
      "messageAlignment": { "type": "MessageAlignment", "default": ".standard" }
    },
    "viewSlots": {
      "headerView": "() -> UIView",
      "footerView": "() -> UIView",
      "emptyStateView": "() -> UIView",
      "errorStateView": "() -> UIView",
      "loadingStateView": "() -> UIView",
      "newMessageIndicatorView": "() -> UIView"
    },
    "formatting": {
      "datePattern": "(Int?) -> String",
      "timePattern": "(Int) -> String",
      "dateSeparatorPattern": "(Int?) -> String",
      "textFormatters": "[CometChatTextFormatter]"
    }
  },
  "events": [],
  "sdkListeners": [
    "onMessageReceived",
    "onMessageEdited",
    "onMessageDeleted",
    "onTypingStarted",
    "onTypingEnded",
    "onMessageReactionAdded",
    "onMessageReactionRemoved"
  ],
  "compositionExample": {
    "description": "MessageList is typically used within CometChatMessages alongside MessageHeader and MessageComposer",
    "components": ["CometChatMessageHeader", "CometChatMessageList", "CometChatMessageComposer"],
    "flow": "User views messages → types in composer → sends message → MessageList updates"
  },
  "types": {
    "BaseMessage": {
      "id": "Int",
      "sender": "User?",
      "receiver": "AppEntity?",
      "sentAt": "Int",
      "type": "String",
      "category": "String"
    },
    "MessageAlignment": {
      "standard": "Outgoing messages on right, incoming on left",
      "left": "All messages aligned to left"
    }
  }
}

Field	Value
Component	`CometChatMessageList`
Package	`CometChatUIKitSwift`
Inherits	`UIViewController`

Where It Fits

CometChatMessageList is the core component for displaying messages in a chat. It’s typically used within CometChatMessages alongside CometChatMessageHeader and CometChatMessageComposer.

import UIKit
import CometChatUIKitSwift
import CometChatSDK

class ChatViewController: UIViewController {
    
    private var messageList: CometChatMessageList!
    
    override func viewDidLoad() {
        super.viewDidLoad()
        setupMessageList()
    }
    
    private func setupMessageList(for user: User) {
        messageList = CometChatMessageList()
        messageList.set(user: user)
        
        // Handle thread replies
        messageList.set(onThreadRepliesClick: { [weak self] message, template in
            self?.openThreadView(for: message)
        })
        
        // Handle reactions
        messageList.set(onReactionClick: { [weak self] reactionCount, message in
            guard let message = message else { return }
            self?.showReactionDetails(reactionCount, for: message)
        })
        
        addChild(messageList)
        view.addSubview(messageList.view)
        messageList.didMove(toParent: self)
    }
    
    private func openThreadView(for message: BaseMessage) {
        let threadMessages = CometChatMessages()
        threadMessages.set(user: message.sender as? User)
        threadMessages.set(parentMessage: message)
        navigationController?.pushViewController(threadMessages, animated: true)
    }
    
    private func showReactionDetails(_ reactionCount: ReactionCount, for message: BaseMessage) {
        // Show reaction details
    }
}

CometChatMessageList integrated within a chat view controller showing message bubbles with thread replies and reaction handling

Minimal Render

import CometChatUIKitSwift
import CometChatSDK

let messageList = CometChatMessageList()
messageList.set(user: user)

Filtering

Use MessagesRequest.MessageRequestBuilder to filter which messages appear in the list. The builder pattern allows chaining multiple filter conditions.

import CometChatUIKitSwift
import CometChatSDK

// Create a custom request builder
let messageRequestBuilder = MessagesRequest.MessageRequestBuilder()
    .set(uid: "user-id")
    .set(limit: 30)
    .set(types: ["text", "image", "video"])

let messageList = CometChatMessageList()
messageList.set(user: user)
messageList.set(messagesRequestBuilder: messageRequestBuilder)

Filter Recipes

Recipe	Code
Text messages only	`.set(types: ["text"])`
Media messages only	`.set(types: ["image", "video", "audio", "file"])`
Search by keyword	`.set(searchKeyword: "hello")`
Limit results	`.set(limit: 50)`
Messages after timestamp	`.set(timestamp: 1234567890)`
Hide deleted messages	`.hideDeletedMessages(true)`
Specific categories	`.set(categories: ["message", "custom"])`

Actions and Events

Callback Props

onThreadRepliesClick

Fires when a user taps on the thread indicator of a message bubble.

import CometChatUIKitSwift
import CometChatSDK

let messageList = CometChatMessageList()

messageList.set(onThreadRepliesClick: { [weak self] message, template in
    guard let self = self else { return }
    
    let threadMessages = CometChatMessages()
    if let user = message.sender as? User {
        threadMessages.set(user: user)
    }
    threadMessages.set(parentMessage: message)
    self.navigationController?.pushViewController(threadMessages, animated: true)
})

onReactionClick

Fires when a user taps on a reaction on a message bubble.

import CometChatUIKitSwift
import CometChatSDK

let messageList = CometChatMessageList()

messageList.set(onReactionClick: { [weak self] reactionCount, message in
    guard let self = self, let message = message else { return }
    print("Reaction \(reactionCount.reaction ?? "") tapped on message \(message.id)")
})

onReactionListItemClick

Fires when a user taps on a specific reaction in the reaction list.

import CometChatUIKitSwift
import CometChatSDK

let messageList = CometChatMessageList()

messageList.set(onReactionListItemClick: { [weak self] messageReaction, message in
    guard let self = self else { return }
    print("User \(messageReaction.reactedBy?.name ?? "") reacted with \(messageReaction.reaction)")
})

onError

Fires when an error occurs while loading messages.

import CometChatUIKitSwift

let messageList = CometChatMessageList()

messageList.set(onError: { error in
    print("Error loading messages: \(error.errorDescription)")
})

onEmpty

Fires when the message list is empty.

import CometChatUIKitSwift

let messageList = CometChatMessageList()

messageList.set(onEmpty: {
    print("No messages found")
})

onLoad

Fires when messages are successfully loaded.

import CometChatUIKitSwift
import CometChatSDK

let messageList = CometChatMessageList()

messageList.set(onLoad: { messages in
    print("Loaded \(messages.count) messages")
})

Actions Reference

Method	Description	Example
`set(onThreadRepliesClick:)`	Triggered when thread indicator is tapped	Open thread view
`set(onReactionClick:)`	Triggered when a reaction is tapped	Show reaction details
`set(onReactionListItemClick:)`	Triggered when reaction list item is tapped	Show who reacted
`set(onError:)`	Triggered when an error occurs	Show error alert
`set(onEmpty:)`	Triggered when list is empty	Show empty state
`set(onLoad:)`	Triggered when messages load	Analytics tracking
`scrollToBottom(isAnimated:)`	Scrolls to the bottom of the list	Navigate to latest
`goToMessage(withId:)`	Scrolls to a specific message	Jump to message

SDK Events (Real-Time, Automatic)

SDK Listener	Internal behavior
`onMessageReceived`	Adds new message to the list
`onMessageEdited`	Updates the edited message in place
`onMessageDeleted`	Removes or marks message as deleted
`onTypingStarted`	Shows typing indicator
`onTypingEnded`	Hides typing indicator
`onMessageReactionAdded`	Updates reaction count on message
`onMessageReactionRemoved`	Updates reaction count on message

Data Manipulation Methods

Programmatically manage messages in the list using these methods.

add(message:)

Adds a new message to the message list.

@discardableResult
public func add(message: BaseMessage) -> Self

Parameter	Type	Description
`message`	`BaseMessage`	The message to add to the list

import CometChatUIKitSwift
import CometChatSDK

let messageList = CometChatMessageList()

// Add a message programmatically
let textMessage = TextMessage(receiverUid: "user-id", text: "Hello!", receiverType: .user)
messageList.add(message: textMessage)

update(message:)

Updates an existing message in the list.

@discardableResult
public func update(message: BaseMessage) -> Self

Parameter	Type	Description
`message`	`BaseMessage`	The message with updated content

import CometChatUIKitSwift
import CometChatSDK

let messageList = CometChatMessageList()

// Update a message after editing
if let editedMessage = existingMessage as? TextMessage {
    editedMessage.text = "Updated message text"
    messageList.update(message: editedMessage)
}

remove(message:)

Removes a message from the list without deleting it from the server.

@discardableResult
public func remove(message: BaseMessage) -> Self

Parameter	Type	Description
`message`	`BaseMessage`	The message to remove from the list

import CometChatUIKitSwift
import CometChatSDK

let messageList = CometChatMessageList()

// Remove a message from the UI
messageList.remove(message: messageToRemove)

delete(message:)

Deletes a message from both the list and the server.

@discardableResult
public func delete(message: BaseMessage) -> Self

Parameter	Type	Description
`message`	`BaseMessage`	The message to delete

import CometChatUIKitSwift
import CometChatSDK

let messageList = CometChatMessageList()

// Delete a message permanently
messageList.delete(message: messageToDelete)

clearList()

Removes all messages from the list.

@discardableResult
public func clearList() -> Self

import CometChatUIKitSwift

let messageList = CometChatMessageList()

// Clear all messages from the list
messageList.clearList()

isEmpty()

Checks if the message list is empty.

public func isEmpty() -> Bool

import CometChatUIKitSwift

let messageList = CometChatMessageList()

// Check if list is empty
if messageList.isEmpty() {
    print("No messages in the list")
}

Connection Management

Manually control the WebSocket connection for the message list.

connect()

Establishes the WebSocket connection for real-time updates. Use this when you need to manually reconnect after disconnecting.

@discardableResult
public func connect() -> Self

import CometChatUIKitSwift

let messageList = CometChatMessageList()

// Manually connect to receive real-time updates
messageList.connect()

disconnect()

Disconnects the WebSocket connection. Use this when you want to temporarily stop receiving real-time updates, such as when the view is not visible.

@discardableResult
public func disconnect() -> Self

import CometChatUIKitSwift

let messageList = CometChatMessageList()

// Disconnect when view disappears
override func viewWillDisappear(_ animated: Bool) {
    super.viewWillDisappear(animated)
    messageList.disconnect()
}

// Reconnect when view appears
override func viewWillAppear(_ animated: Bool) {
    super.viewWillAppear(animated)
    messageList.connect()
}

Custom View Slots

Slot	Signature	Replaces
`headerView`	`UIView`	Header above message list
`footerView`	`UIView`	Footer below message list
`emptyView`	`UIView`	Empty state display
`errorView`	`UIView`	Error state display
`loadingView`	`UIView`	Loading state display
`newMessageIndicatorView`	`UIView`	New message indicator

set(headerView:)

Replaces the default header with a custom view.


Signature	`(UIView) -> Self`
Replaces	Default header above message list

import UIKit
import CometChatUIKitSwift

let messageList = CometChatMessageList()

let headerView = UIView()
headerView.backgroundColor = UIColor.systemGray6

let label = UILabel()
label.text = "Pinned Messages"
label.font = UIFont.systemFont(ofSize: 14, weight: .medium)
label.textColor = UIColor.secondaryLabel
headerView.addSubview(label)

messageList.set(headerView: headerView)

set(footerView:)

Replaces the default footer with a custom view.


Signature	`(UIView) -> Self`
Replaces	Default footer below message list

import UIKit
import CometChatUIKitSwift

let messageList = CometChatMessageList()

let footerView = UIView()
footerView.backgroundColor = UIColor.systemGray6

let quickRepliesStack = UIStackView()
quickRepliesStack.axis = .horizontal
quickRepliesStack.spacing = 8

let replies = ["👍", "Thanks!", "Got it"]
for reply in replies {
    let button = UIButton(type: .system)
    button.setTitle(reply, for: .normal)
    button.backgroundColor = UIColor.systemBackground
    button.layer.cornerRadius = 16
    quickRepliesStack.addArrangedSubview(button)
}

footerView.addSubview(quickRepliesStack)
messageList.set(footerView: footerView)

set(emptyView:)

Replaces the default empty state view with a custom view.


Signature	`(UIView) -> Self`
Replaces	Default empty state when no messages exist

import UIKit
import CometChatUIKitSwift

let messageList = CometChatMessageList()

let emptyView = UIView()
let imageView = UIImageView(image: UIImage(systemName: "bubble.left.and.bubble.right"))
imageView.tintColor = UIColor.tertiaryLabel

let label = UILabel()
label.text = "No messages yet. Start the conversation!"
label.textColor = UIColor.secondaryLabel
label.textAlignment = .center

emptyView.addSubview(imageView)
emptyView.addSubview(label)

messageList.set(emptyView: emptyView)

set(errorView:)

Replaces the default error state view with a custom view.


Signature	`(UIView) -> Self`
Replaces	Default error state when loading fails

import UIKit
import CometChatUIKitSwift

let messageList = CometChatMessageList()

let errorView = UIView()
let errorLabel = UILabel()
errorLabel.text = "Something went wrong!"
errorLabel.textColor = .red
errorLabel.textAlignment = .center

let retryButton = UIButton(type: .system)
retryButton.setTitle("Retry", for: .normal)

errorView.addSubview(errorLabel)
errorView.addSubview(retryButton)

messageList.set(errorView: errorView)

set(loadingView:)

Replaces the default loading indicator with a custom view.


Signature	`(UIView) -> Self`
Replaces	Default loading indicator

import UIKit
import CometChatUIKitSwift

let messageList = CometChatMessageList()

let loadingView = UIActivityIndicatorView(style: .large)
loadingView.color = UIColor.systemBlue
loadingView.startAnimating()

messageList.set(loadingView: loadingView)

set(newMessageIndicatorView:)

Replaces the default new message indicator with a custom view.


Signature	`(UIView) -> Self`
Replaces	Default new message indicator

import UIKit
import CometChatUIKitSwift

let messageList = CometChatMessageList()

let newMessageIndicatorView = NewUnreadMessageIndicator()
messageList.set(newMessageIndicatorView: newMessageIndicatorView)

class NewUnreadMessageIndicator: UIView {
    
    private let label: UILabel = {
        let label = UILabel()
        label.text = "New Messages ↓"
        label.textColor = .white
        label.font = UIFont.systemFont(ofSize: 14, weight: .medium)
        label.textAlignment = .center
        return label
    }()
    
    override init(frame: CGRect) {
        super.init(frame: frame)
        backgroundColor = UIColor.systemBlue
        layer.cornerRadius = 16
        
        addSubview(label)
        label.translatesAutoresizingMaskIntoConstraints = false
        NSLayoutConstraint.activate([
            label.centerXAnchor.constraint(equalTo: centerXAnchor),
            label.centerYAnchor.constraint(equalTo: centerYAnchor)
        ])
    }
    
    required init?(coder: NSCoder) {
        fatalError("init(coder:) has not been implemented")
    }
}

Text Formatters

Customize how text is displayed in messages using text formatters.

import CometChatUIKitSwift
import CometChatSDK

let myCustomTextFormatter = MyCustomTextFormatter(trackingCharacter: "#")

let cometChatMessages = CometChatMessages()
    .set(user: user)
    .set(textFormatter: [myCustomTextFormatter])

set(textFormatters:)

Sets custom text formatters for message text display.

@discardableResult
public func set(textFormatters: [CometChatTextFormatter]) -> Self

Parameter	Type	Description
`textFormatters`	`[CometChatTextFormatter]`	Array of text formatters to apply

import CometChatUIKitSwift

let messageList = CometChatMessageList()

let hashtagFormatter = HashtagTextFormatter(trackingCharacter: "#")
let mentionFormatter = MentionTextFormatter(trackingCharacter: "@")

messageList.set(textFormatters: [hashtagFormatter, mentionFormatter])

setMentionAllLabel(::)

Customizes the label displayed for @all mentions.

@discardableResult
public func setMentionAllLabel(_ title: String, _ subtitle: String) -> Self

Parameter	Type	Description
`title`	`String`	The title for the @all mention
`subtitle`	`String`	The subtitle for the @all mention

import CometChatUIKitSwift

let messageList = CometChatMessageList()

// Customize the @all mention label
messageList.setMentionAllLabel("Everyone", "Notify all members")

You can create a custom text formatter:

import Foundation
import CometChatSDK
import CometChatUIKitSwift

class MyCustomTextFormatter: CometChatTextFormatter {
    
    override func getRegex() -> String {
        return "(\\bsure\\b)"
    }

    override func getTrackingCharacter() -> Character {
        return "#"
    }

    override func search(string: String, suggestedItems: ((_: [SuggestionItem]) -> ())? = nil) {
        // This function would call an API or perform a local search
    }

    override func onScrollToBottom(suggestionItemList: [SuggestionItem], listItem: ((_: [SuggestionItem]) -> ())?) {
        // This function would call the next page of an API
    }

    override func onItemClick(suggestedItem: SuggestionItem, user: User?, group: Group?) {
        // Handle clicked item
    }

    override func handlePreMessageSend(baseMessage: BaseMessage, suggestionItemList: [SuggestionItem]) {
        // Modify the message before it's sent
    }

    override func prepareMessageString(
        baseMessage: BaseMessage,
        regexString: String,
        alignment: MessageBubbleAlignment = .left,
        formattingType: FormattingType
    ) -> NSAttributedString {
        let attrString = NSMutableAttributedString(string: "SURE")
        if alignment == .left {
            // Received message styling
            attrString.addAttribute(.foregroundColor, value: UIColor.blue, range: NSRange(location: 0, length: attrString.length))
        } else {
            // Sent message styling
            attrString.addAttribute(.foregroundColor, value: UIColor.green, range: NSRange(location: 0, length: attrString.length))
        }
        attrString.addAttribute(.font, value: UIFont.boldSystemFont(ofSize: 18), range: NSRange(location: 0, length: attrString.length))
        return attrString
    }

    override func onTextTapped(baseMessage: BaseMessage, tappedText: String, controller: UIViewController?) {
        // Handle text tap action
    }
}

AI Features

Configure AI-powered features for the message list.

enableSmartReplies

Enables AI-powered smart reply suggestions.


Type	`Bool`
Default	`false`

import CometChatUIKitSwift

let messageList = CometChatMessageList()
messageList.enableSmartReplies = true

enableConversationStarters

Enables AI-powered conversation starter suggestions.


Type	`Bool`
Default	`false`

import CometChatUIKitSwift

let messageList = CometChatMessageList()
messageList.enableConversationStarters = true

enableConversationSummary

Enables AI-powered conversation summary feature.


Type	`Bool`
Default	`false`

import CometChatUIKitSwift

let messageList = CometChatMessageList()
messageList.enableConversationSummary = true

set(smartRepliesKeywords:)

Sets keywords that trigger smart reply suggestions.

@discardableResult
public func set(smartRepliesKeywords: [String]) -> Self

Parameter	Type	Description
`smartRepliesKeywords`	`[String]`	Keywords that trigger smart replies

import CometChatUIKitSwift

let messageList = CometChatMessageList()

// Set keywords that trigger smart replies
messageList.set(smartRepliesKeywords: ["help", "question", "support"])

set(smartRepliesDelayDuration:)

Sets the delay duration before showing smart reply suggestions.

@discardableResult
public func set(smartRepliesDelayDuration: TimeInterval) -> Self

Parameter	Type	Description
`smartRepliesDelayDuration`	`TimeInterval`	Delay in seconds before showing suggestions

import CometChatUIKitSwift

let messageList = CometChatMessageList()

// Set a 2-second delay before showing smart replies
messageList.set(smartRepliesDelayDuration: 2.0)

Reactions Configuration

Configure how reactions are displayed and behave in the message list.

reactionsConfiguration

Configuration object for the reactions feature.


Type	`ReactionsConfiguration`
Default	`ReactionsConfiguration()`

import CometChatUIKitSwift

let messageList = CometChatMessageList()

let reactionsConfig = ReactionsConfiguration()
reactionsConfig.reactionLimit = 5
reactionsConfig.showReactionCount = true

messageList.reactionsConfiguration = reactionsConfig

reactionListConfiguration

Configuration object for the reaction list display.


Type	`ReactionListConfiguration`
Default	`ReactionListConfiguration()`

import CometChatUIKitSwift

let messageList = CometChatMessageList()

let reactionListConfig = ReactionListConfiguration()
reactionListConfig.showUserNames = true

messageList.reactionListConfiguration = reactionListConfig

quickReactionsConfiguration

Configuration object for quick reactions.


Type	`QuickReactionsConfiguration`
Default	`QuickReactionsConfiguration()`

import CometChatUIKitSwift

let messageList = CometChatMessageList()

let quickReactionsConfig = QuickReactionsConfiguration()
quickReactionsConfig.quickReactions = ["👍", "❤️", "😂", "😮", "😢"]

messageList.quickReactionsConfiguration = quickReactionsConfig

messageInformationConfiguration

Configuration object for message information display.


Type	`MessageInformationConfiguration`
Default	`MessageInformationConfiguration()`

import CometChatUIKitSwift

let messageList = CometChatMessageList()

let messageInfoConfig = MessageInformationConfiguration()
messageInfoConfig.showReadReceipts = true
messageInfoConfig.showDeliveryReceipts = true

messageList.messageInformationConfiguration = messageInfoConfig

Styling

Style Hierarchy

Global styles (CometChatMessageList.style) apply to all instances
Instance styles override global for specific instances

Global Level Styling

import UIKit
import CometChatUIKitSwift

// Apply global styles that affect all CometChatMessageList instances
CometChatMessageList.style.backgroundColor = UIColor.systemBackground
CometChatMessageList.style.emptyStateTitleColor = UIColor.label
CometChatMessageList.style.emptyStateTitleFont = UIFont.systemFont(ofSize: 20, weight: .bold)
CometChatMessageList.style.emptyStateSubtitleColor = UIColor.secondaryLabel

// Customize message bubble styles
CometChatMessageList.messageBubbleStyle.outgoing.backgroundColor = UIColor.systemBlue
CometChatMessageList.messageBubbleStyle.incoming.backgroundColor = UIColor.systemGray5

Instance Level Styling

import UIKit
import CometChatUIKitSwift

// Create a custom style for a specific instance
let messageListStyle = MessageListStyle()
messageListStyle.backgroundColor = UIColor(red: 0.95, green: 0.95, blue: 0.97, alpha: 1.0)
messageListStyle.borderWidth = 0
messageListStyle.borderColor = .clear

let messageList = CometChatMessageList()
messageList.style = messageListStyle

CometChatMessageList with custom styling applied showing modified background color and message bubble appearance

Key Style Properties

Property	Type	Default	Description
`backgroundColor`	`UIColor`	`CometChatTheme.backgroundColor01`	Background color of the list
`borderWidth`	`CGFloat`	`0`	Border width for the component
`borderColor`	`UIColor`	`.clear`	Border color for the component
`cornerRadius`	`CometChatCornerStyle?`	`nil`	Corner radius for the component
`shimmerGradientColor1`	`UIColor`	`CometChatTheme.backgroundColor04`	First shimmer gradient color
`shimmerGradientColor2`	`UIColor`	`CometChatTheme.backgroundColor03`	Second shimmer gradient color
`emptyStateTitleColor`	`UIColor`	`CometChatTheme.textColorPrimary`	Empty state title color
`emptyStateTitleFont`	`UIFont`	`CometChatTypography.Heading3.bold`	Empty state title font
`emptyStateSubtitleColor`	`UIColor`	`CometChatTheme.textColorSecondary`	Empty state subtitle color
`emptyStateSubtitleFont`	`UIFont`	`CometChatTypography.Body.regular`	Empty state subtitle font
`errorStateTitleColor`	`UIColor`	`CometChatTheme.textColorPrimary`	Error state title color
`errorStateTitleFont`	`UIFont`	`CometChatTypography.Heading3.bold`	Error state title font
`newMessageIndicatorTextColor`	`UIColor?`	`nil`	New message indicator text color
`newMessageIndicatorBackgroundColor`	`UIColor?`	`nil`	New message indicator background

Style Properties

emojiKeyboardStyle

Customizes the appearance of the emoji keyboard.


Type	`EmojiKeyboardStyle`
Default	`EmojiKeyboardStyle()`

import CometChatUIKitSwift

let messageList = CometChatMessageList()

let emojiKeyboardStyle = EmojiKeyboardStyle()
emojiKeyboardStyle.backgroundColor = UIColor.systemBackground
emojiKeyboardStyle.borderColor = UIColor.systemGray4

messageList.emojiKeyboardStyle = emojiKeyboardStyle

dateSeparatorStyle

Customizes the appearance of date separators between messages.


Type	`DateSeparatorStyle`
Default	`DateSeparatorStyle()`

import CometChatUIKitSwift

let messageList = CometChatMessageList()

let dateSeparatorStyle = DateSeparatorStyle()
dateSeparatorStyle.textColor = UIColor.secondaryLabel
dateSeparatorStyle.textFont = UIFont.systemFont(ofSize: 12, weight: .medium)
dateSeparatorStyle.backgroundColor = UIColor.systemGray6

messageList.dateSeparatorStyle = dateSeparatorStyle

newMessageIndicatorStyle

Customizes the appearance of the new message indicator.


Type	`NewMessageIndicatorStyle`
Default	`NewMessageIndicatorStyle()`

import CometChatUIKitSwift

let messageList = CometChatMessageList()

let newMessageIndicatorStyle = NewMessageIndicatorStyle()
newMessageIndicatorStyle.textColor = UIColor.white
newMessageIndicatorStyle.backgroundColor = UIColor.systemBlue
newMessageIndicatorStyle.cornerRadius = 16

messageList.newMessageIndicatorStyle = newMessageIndicatorStyle

messageBubbleStyle

Customizes the appearance of message bubbles.


Type	`MessageBubbleStyle`
Default	`MessageBubbleStyle()`

import CometChatUIKitSwift

let messageList = CometChatMessageList()

let messageBubbleStyle = MessageBubbleStyle()
messageBubbleStyle.outgoing.backgroundColor = UIColor.systemBlue
messageBubbleStyle.incoming.backgroundColor = UIColor.systemGray5
messageBubbleStyle.outgoing.textColor = UIColor.white
messageBubbleStyle.incoming.textColor = UIColor.label

messageList.messageBubbleStyle = messageBubbleStyle

actionBubbleStyle

Customizes the appearance of action message bubbles (e.g., group actions).


Type	`ActionBubbleStyle`
Default	`ActionBubbleStyle()`

import CometChatUIKitSwift

let messageList = CometChatMessageList()

let actionBubbleStyle = ActionBubbleStyle()
actionBubbleStyle.backgroundColor = UIColor.systemGray6
actionBubbleStyle.textColor = UIColor.secondaryLabel
actionBubbleStyle.textFont = UIFont.systemFont(ofSize: 13, weight: .regular)

messageList.actionBubbleStyle = actionBubbleStyle

callActionBubbleStyle

Customizes the appearance of call action message bubbles.


Type	`CallActionBubbleStyle`
Default	`CallActionBubbleStyle()`

import CometChatUIKitSwift

let messageList = CometChatMessageList()

let callActionBubbleStyle = CallActionBubbleStyle()
callActionBubbleStyle.backgroundColor = UIColor.systemGreen.withAlphaComponent(0.1)
callActionBubbleStyle.iconTintColor = UIColor.systemGreen
callActionBubbleStyle.textColor = UIColor.label

messageList.callActionBubbleStyle = callActionBubbleStyle

Customization Matrix

What to change	Where	Property/API	Example
Background color	Style	`backgroundColor`	`UIColor.systemBackground`
Empty state text	Style	`emptyStateTitleColor`, `emptyStateTitleFont`	Custom colors and fonts
Error state text	Style	`errorStateTitleColor`, `errorStateTitleFont`	Custom colors and fonts
Loading shimmer	Style	`shimmerGradientColor1`, `shimmerGradientColor2`	Custom gradient colors
Outgoing bubble	Style	`messageBubbleStyle.outgoing`	`UIColor.systemBlue`
Incoming bubble	Style	`messageBubbleStyle.incoming`	`UIColor.systemGray5`
Hide avatars	Property	`hideAvatar`	`messageList.hideAvatar = true`
Hide receipts	Property	`hideReceipts`	`messageList.hideReceipts = true`
Custom header	View Slot	`set(headerView:)`	See Custom View Slots section

Props

All props are optional. Sorted alphabetically.

actionBubbleStyle

Customizes the appearance of action message bubbles.


Type	`ActionBubbleStyle`
Default	`ActionBubbleStyle()`

callActionBubbleStyle

Customizes the appearance of call action message bubbles.


Type	`CallActionBubbleStyle`
Default	`CallActionBubbleStyle()`

dateSeparatorStyle

Customizes the appearance of date separators.


Type	`DateSeparatorStyle`
Default	`DateSeparatorStyle()`

disableSoundForMessages

Disables notification sounds for new messages.


Type	`Bool`
Default	`false`

disableSwipeToReply

Disables the swipe-to-reply gesture on messages.


Type	`Bool`
Default	`false`

import CometChatUIKitSwift

let messageList = CometChatMessageList()
messageList.disableSwipeToReply = true

emojiKeyboardStyle

Customizes the appearance of the emoji keyboard.


Type	`EmojiKeyboardStyle`
Default	`EmojiKeyboardStyle()`

emptySubtitleText

Custom subtitle text for the empty state view.


Type	`String`
Default	`""`

import CometChatUIKitSwift

let messageList = CometChatMessageList()
messageList.emptySubtitleText = "Send a message to start the conversation"

emptyTitleText

Custom title text for the empty state view.


Type	`String`
Default	`"No Messages"`

import CometChatUIKitSwift

let messageList = CometChatMessageList()
messageList.emptyTitleText = "No messages yet"

enableConversationStarters

Enables AI-powered conversation starter suggestions.


Type	`Bool`
Default	`false`

enableConversationSummary

Enables AI-powered conversation summary feature.


Type	`Bool`
Default	`false`

enableSmartReplies

Enables AI-powered smart reply suggestions.


Type	`Bool`
Default	`false`

errorSubtitleText

Custom subtitle text for the error state view.


Type	`String`
Default	`""`

import CometChatUIKitSwift

let messageList = CometChatMessageList()
messageList.errorSubtitleText = "Please check your connection and try again"

errorTitleText

Custom title text for the error state view.


Type	`String`
Default	`"Something went wrong"`

import CometChatUIKitSwift

let messageList = CometChatMessageList()
messageList.errorTitleText = "Unable to load messages"

hideAvatar

Hides the sender’s avatar in message bubbles.


Type	`Bool`
Default	`false`

hideBubbleHeader

Hides the header section of message bubbles (sender name, timestamp).


Type	`Bool`
Default	`false`

import CometChatUIKitSwift

let messageList = CometChatMessageList()
messageList.hideBubbleHeader = true

hideCopyMessageOption

Hides the copy message option in message actions.


Type	`Bool`
Default	`false`

hideDateSeparator

Hides the date separator between messages.


Type	`Bool`
Default	`false`

hideDeleteMessageOption

Hides the delete message option in message actions.


Type	`Bool`
Default	`false`

hideEditMessageOption

Hides the edit message option in message actions.


Type	`Bool`
Default	`false`

hideEmptyView

Hides the empty state view when no messages are available.


Type	`Bool`
Default	`false`

hideErrorView

Hides the error view when an error occurs.


Type	`Bool`
Default	`false`

hideFlagMessageOption

Hides the flag/report message option in message actions.


Type	`Bool`
Default	`false`

import CometChatUIKitSwift

let messageList = CometChatMessageList()
messageList.hideFlagMessageOption = true

hideFooterView

Hides the footer view of the message list.


Type	`Bool`
Default	`false`

hideGroupActionMessages

Hides group action messages (join/leave notifications).


Type	`Bool`
Default	`false`

hideHeaderView

Hides the header view of the message list.


Type	`Bool`
Default	`false`

hideLoadingView

Hides the loading view when fetching messages.


Type	`Bool`
Default	`false`

hideMessageInfoOption

Hides the message info option in message actions.


Type	`Bool`
Default	`false`

hideMessagePrivatelyOption

Hides the option to message privately.


Type	`Bool`
Default	`false`

hideNewMessageIndicator

Hides the new message indicator.


Type	`Bool`
Default	`false`

hideReactionOption

Hides the reaction option on messages.


Type	`Bool`
Default	`false`

hideReceipts

Hides message read receipts (ticks).


Type	`Bool`
Default	`false`

hideReplyInThreadOption

Hides the reply in thread option.


Type	`Bool`
Default	`false`

hideReplyMessageOption

Hides the reply to message option in message actions.


Type	`Bool`
Default	`false`

import CometChatUIKitSwift

let messageList = CometChatMessageList()
messageList.hideReplyMessageOption = true

hideShareMessageOption

Hides the share message option in message actions.


Type	`Bool`
Default	`false`

import CometChatUIKitSwift

let messageList = CometChatMessageList()
messageList.hideShareMessageOption = true

hideTranslateMessageOption

Hides the message translation option.


Type	`Bool`
Default	`false`

messageAlignment

Sets the alignment of messages in the list.


Type	`MessageAlignment`
Default	`.standard`

messageBubbleStyle

Customizes the appearance of message bubbles.


Type	`MessageBubbleStyle`
Default	`MessageBubbleStyle()`

messageInformationConfiguration

Configuration object for message information display.


Type	`MessageInformationConfiguration`
Default	`MessageInformationConfiguration()`

messagesRequestBuilder

Custom request builder for filtering messages.


Type	`MessagesRequest.MessageRequestBuilder?`
Default	`nil`

newMessageIndicatorStyle

Customizes the appearance of the new message indicator.


Type	`NewMessageIndicatorStyle`
Default	`NewMessageIndicatorStyle()`

quickReactionsConfiguration

Configuration object for quick reactions.


Type	`QuickReactionsConfiguration`
Default	`QuickReactionsConfiguration()`

reactionsConfiguration

Configuration object for the reactions feature.


Type	`ReactionsConfiguration`
Default	`ReactionsConfiguration()`

reactionListConfiguration

Configuration object for the reaction list display.


Type	`ReactionListConfiguration`
Default	`ReactionListConfiguration()`

reactionsRequestBuilder

Custom request builder for fetching reactions.


Type	`ReactionsRequest.ReactionsRequestBuilder?`
Default	`nil`

scrollToBottomOnNewMessages

Automatically scrolls to bottom when new messages arrive.


Type	`Bool`
Default	`true`

showMarkAsUnreadOption

Shows the “Mark as unread” option in message actions.


Type	`Bool`
Default	`false`

startFromUnreadMessages

Starts the message list from the first unread message.


Type	`Bool`
Default	`false`

textFormatters

Array of text formatters for customizing message text display.


Type	`[CometChatTextFormatter]`
Default	`[]`

Events

The MessageList component provides callback events for handling state changes.

set(onLoad:)

Fires when messages are successfully loaded.

@discardableResult
public func set(onLoad: @escaping ([BaseMessage]) -> Void) -> Self

Parameter	Type	Description
`onLoad`	`([BaseMessage]) -> Void`	Callback with loaded messages

import CometChatUIKitSwift
import CometChatSDK

let messageList = CometChatMessageList()

messageList.set(onLoad: { messages in
    print("Loaded \(messages.count) messages")
    // Perform analytics tracking or other actions
})

set(onEmpty:)

Fires when the message list is empty.

@discardableResult
public func set(onEmpty: @escaping () -> Void) -> Self

Parameter	Type	Description
`onEmpty`	`() -> Void`	Callback when list is empty

import CometChatUIKitSwift

let messageList = CometChatMessageList()

messageList.set(onEmpty: {
    print("No messages found")
    // Show custom empty state or prompt user to start conversation
})

Date Time Formatter

Customize how timestamps appear in the message list using the CometChatDateTimeFormatter.

Global Level Formatting

import CometChatUIKitSwift

// Customize time format
CometChatMessageList.dateTimeFormatter.time = { timestamp in
    let date = Date(timeIntervalSince1970: TimeInterval(timestamp))
    let formatter = DateFormatter()
    formatter.dateFormat = "HH:mm"
    return formatter.string(from: date)
}

// Customize today format
CometChatMessageList.dateTimeFormatter.today = { timestamp in
    let date = Date(timeIntervalSince1970: TimeInterval(timestamp))
    let formatter = DateFormatter()
    formatter.dateFormat = "h:mm a"
    return "Today • " + formatter.string(from: date)
}

// Customize older dates format
CometChatMessageList.dateTimeFormatter.otherDay = { timestamp in
    let date = Date(timeIntervalSince1970: TimeInterval(timestamp))
    let formatter = DateFormatter()
    formatter.dateFormat = "dd MMM yyyy"
    return formatter.string(from: date)
}

Instance Level Formatting

set(datePattern:)

Sets a custom date pattern for message timestamps.

@discardableResult
public func set(datePattern: @escaping (Int?) -> String) -> Self

Parameter	Type	Description
`datePattern`	`(Int?) -> String`	Closure that formats timestamp to date string

import CometChatUIKitSwift

let messageList = CometChatMessageList()

messageList.set(datePattern: { timestamp in
    guard let timestamp = timestamp else { return "" }
    let date = Date(timeIntervalSince1970: TimeInterval(timestamp / 1000))
    let formatter = DateFormatter()
    formatter.dateFormat = "dd-MM-yyyy"
    return formatter.string(from: date)
})

set(timePattern:)

Sets a custom time pattern for message timestamps.

@discardableResult
public func set(timePattern: @escaping (Int) -> String) -> Self

Parameter	Type	Description
`timePattern`	`(Int) -> String`	Closure that formats timestamp to time string

import CometChatUIKitSwift

let messageList = CometChatMessageList()

messageList.set(timePattern: { timestamp in
    let date = Date(timeIntervalSince1970: TimeInterval(timestamp))
    let formatter = DateFormatter()
    formatter.dateFormat = "HH:mm"
    return formatter.string(from: date)
})

set(dateSeparatorPattern:)

Sets a custom pattern for date separators between messages.

@discardableResult
public func set(dateSeparatorPattern: @escaping (Int?) -> String) -> Self

Parameter	Type	Description
`dateSeparatorPattern`	`(Int?) -> String`	Closure that formats timestamp to date separator string

import CometChatUIKitSwift

let messageList = CometChatMessageList()

messageList.set(dateSeparatorPattern: { timestamp in
    guard let timestamp = timestamp else { return "" }
    let date = Date(timeIntervalSince1970: TimeInterval(timestamp))
    
    if Calendar.current.isDateInToday(date) {
        return "Today"
    } else if Calendar.current.isDateInYesterday(date) {
        return "Yesterday"
    } else {
        let formatter = DateFormatter()
        formatter.dateFormat = "EEEE, MMM d"
        return formatter.string(from: date)
    }
})

Available Formatters

Formatter	Purpose	Default Format
`time`	Standard time display	`h:mm a`
`today`	Messages sent today	`Today`
`yesterday`	Messages from yesterday	`Yesterday`
`lastweek`	Messages within last week	Day name
`otherDay`	Older messages	`MMM d, yyyy`
`datePattern`	Custom date pattern	Configurable
`timePattern`	Custom time pattern	Configurable
`dateSeparatorPattern`	Date separator between messages	Configurable

Common Patterns

Hide message options

let messageList = CometChatMessageList()
messageList.set(user: user)
messageList.hideReplyInThreadOption = true
messageList.hideEditMessageOption = true
messageList.hideDeleteMessageOption = true
messageList.hideReactionOption = true
messageList.hideCopyMessageOption = true

Disable sounds

let messageList = CometChatMessageList()
messageList.set(user: user)
messageList.disableSoundForMessages = true

Custom empty state

let messageList = CometChatMessageList()
messageList.set(user: user)

messageList.set(emptyStateView: {
    let label = UILabel()
    label.text = "Start a conversation!"
    label.textAlignment = .center
    label.textColor = .secondaryLabel
    return label
})

Scroll to bottom on new messages

let messageList = CometChatMessageList()
messageList.set(user: user)
messageList.scrollToBottomOnNewMessages = true

Hide UI elements

let messageList = CometChatMessageList()
messageList.set(user: user)
messageList.hideAvatar = true
messageList.hideReceipts = true
messageList.hideDateSeparator = true
messageList.hideHeaderView = true
messageList.hideFooterView = true

Messages - Parent component containing MessageList
Message Composer - Send messages in a conversation
Message Header - Display user/group details
Message Template - Create custom message bubble templates
Threaded Messages - Display threaded conversations

​Where It Fits

​Minimal Render

​Filtering

​Filter Recipes

​Actions and Events

​Callback Props

​onThreadRepliesClick

​onReactionClick

​onReactionListItemClick

​onError

​onEmpty

​onLoad

​Actions Reference

​SDK Events (Real-Time, Automatic)

​Data Manipulation Methods

​add(message:)

​update(message:)

​remove(message:)

​delete(message:)

​clearList()

​isEmpty()

​Connection Management

​connect()

​disconnect()

​Custom View Slots

​set(headerView:)

​set(footerView:)

​set(emptyView:)

​set(errorView:)

​set(loadingView:)

​set(newMessageIndicatorView:)

​Text Formatters

​set(textFormatters:)

​setMentionAllLabel(::)

​AI Features

​enableSmartReplies

​enableConversationStarters

​enableConversationSummary

​set(smartRepliesKeywords:)

​set(smartRepliesDelayDuration:)

​Reactions Configuration

​reactionsConfiguration

​reactionListConfiguration

​quickReactionsConfiguration

​messageInformationConfiguration

​Styling

​Style Hierarchy

​Global Level Styling

​Instance Level Styling

​Key Style Properties

​Style Properties

​emojiKeyboardStyle

​dateSeparatorStyle

​newMessageIndicatorStyle

​messageBubbleStyle

​actionBubbleStyle

​callActionBubbleStyle

​Customization Matrix

​Props

​actionBubbleStyle

​callActionBubbleStyle

​dateSeparatorStyle

​disableSoundForMessages

​disableSwipeToReply

​emojiKeyboardStyle

​emptySubtitleText

​emptyTitleText

​enableConversationStarters

​enableConversationSummary

​enableSmartReplies

​errorSubtitleText

​errorTitleText

​hideAvatar

​hideBubbleHeader

​hideCopyMessageOption

​hideDateSeparator

​hideDeleteMessageOption

​hideEditMessageOption

​hideEmptyView

​hideErrorView

Where It Fits

Minimal Render

Filtering

Filter Recipes

Actions and Events

Callback Props

onThreadRepliesClick

onReactionClick

onReactionListItemClick

onError

onEmpty

onLoad

Actions Reference

SDK Events (Real-Time, Automatic)

Data Manipulation Methods

add(message:)

update(message:)

remove(message:)

delete(message:)

clearList()

isEmpty()

Connection Management

connect()

disconnect()

Custom View Slots

set(headerView:)

set(footerView:)

set(emptyView:)

set(errorView:)

set(loadingView:)

set(newMessageIndicatorView:)

Text Formatters

set(textFormatters:)

setMentionAllLabel(::)

AI Features

enableSmartReplies

enableConversationStarters

enableConversationSummary

set(smartRepliesKeywords:)

set(smartRepliesDelayDuration:)

Reactions Configuration

reactionsConfiguration

reactionListConfiguration

quickReactionsConfiguration

messageInformationConfiguration

Styling

Style Hierarchy

Global Level Styling

Instance Level Styling

Key Style Properties

Style Properties

emojiKeyboardStyle

dateSeparatorStyle

newMessageIndicatorStyle

messageBubbleStyle

actionBubbleStyle

callActionBubbleStyle

Customization Matrix

Props

actionBubbleStyle

callActionBubbleStyle

dateSeparatorStyle

disableSoundForMessages

disableSwipeToReply

emojiKeyboardStyle

emptySubtitleText

emptyTitleText

enableConversationStarters

enableConversationSummary

enableSmartReplies

errorSubtitleText

errorTitleText

hideAvatar

hideBubbleHeader

hideCopyMessageOption

hideDateSeparator

hideDeleteMessageOption

hideEditMessageOption

hideEmptyView

hideErrorView