> ## Documentation Index > Fetch the complete documentation index at: https://cometchat-22654f5b-docs-rn-guide-message-privately.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Message List > Display CometChat iOS UI Kit messages with text, media, reactions, threads, real-time updates, filters, and message callbacks. 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 ```json theme={null} { "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`. ```swift lines theme={null} 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 ```swift lines theme={null} import CometChatUIKitSwift import CometChatSDK let messageList = CometChatMessageList() messageList.set(user: user) ``` CometChatMessageList showing minimal render with default configuration displaying messages for a user conversation *** ## Filtering Use `MessagesRequest.MessageRequestBuilder` to filter which messages appear in the list. The builder pattern allows chaining multiple filter conditions. ```swift lines theme={null} 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. ```swift lines theme={null} 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. ```swift lines theme={null} 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. ```swift lines theme={null} 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. ```swift lines theme={null} import CometChatUIKitSwift let messageList = CometChatMessageList() messageList.set(onError: { error in print("Error loading messages: \(error.errorDescription)") }) ``` #### onEmpty Fires when the message list is empty. ```swift lines theme={null} import CometChatUIKitSwift let messageList = CometChatMessageList() messageList.set(onEmpty: { print("No messages found") }) ``` #### onLoad Fires when messages are successfully loaded. ```swift lines theme={null} 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. ```swift lines theme={null} @discardableResult public func add(message: BaseMessage) -> Self ``` | Parameter | Type | Description | | --------- | ------------- | ------------------------------ | | `message` | `BaseMessage` | The message to add to the list | ```swift lines theme={null} 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. ```swift lines theme={null} @discardableResult public func update(message: BaseMessage) -> Self ``` | Parameter | Type | Description | | --------- | ------------- | -------------------------------- | | `message` | `BaseMessage` | The message with updated content | ```swift lines theme={null} 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. ```swift lines theme={null} @discardableResult public func remove(message: BaseMessage) -> Self ``` | Parameter | Type | Description | | --------- | ------------- | ----------------------------------- | | `message` | `BaseMessage` | The message to remove from the list | ```swift lines theme={null} 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. ```swift lines theme={null} @discardableResult public func delete(message: BaseMessage) -> Self ``` | Parameter | Type | Description | | --------- | ------------- | --------------------- | | `message` | `BaseMessage` | The message to delete | ```swift lines theme={null} import CometChatUIKitSwift import CometChatSDK let messageList = CometChatMessageList() // Delete a message permanently messageList.delete(message: messageToDelete) ``` ### clearList() Removes all messages from the list. ```swift lines theme={null} @discardableResult public func clearList() -> Self ``` ```swift lines theme={null} import CometChatUIKitSwift let messageList = CometChatMessageList() // Clear all messages from the list messageList.clearList() ``` ### isEmpty() Checks if the message list is empty. ```swift lines theme={null} public func isEmpty() -> Bool ``` ```swift lines theme={null} 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. ```swift lines theme={null} @discardableResult public func connect() -> Self ``` ```swift lines theme={null} 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. ```swift lines theme={null} @discardableResult public func disconnect() -> Self ``` ```swift lines theme={null} 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 | ```swift lines theme={null} 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 | ```swift lines theme={null} 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 | ```swift lines theme={null} 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 | ```swift lines theme={null} 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 | ```swift lines theme={null} 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 | ```swift lines theme={null} 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. ```swift lines theme={null} 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. ```swift lines theme={null} @discardableResult public func set(textFormatters: [CometChatTextFormatter]) -> Self ``` | Parameter | Type | Description | | ---------------- | -------------------------- | --------------------------------- | | `textFormatters` | `[CometChatTextFormatter]` | Array of text formatters to apply | ```swift lines theme={null} 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. ```swift lines theme={null} @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 | ```swift lines theme={null} import CometChatUIKitSwift let messageList = CometChatMessageList() // Customize the @all mention label messageList.setMentionAllLabel("Everyone", "Notify all members") ``` You can create a custom text formatter: ```swift lines theme={null} 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` | ```swift lines theme={null} import CometChatUIKitSwift let messageList = CometChatMessageList() messageList.enableSmartReplies = true ``` ### enableConversationStarters Enables AI-powered conversation starter suggestions. | | | | ------- | ------- | | Type | `Bool` | | Default | `false` | ```swift lines theme={null} import CometChatUIKitSwift let messageList = CometChatMessageList() messageList.enableConversationStarters = true ``` ### enableConversationSummary Enables AI-powered conversation summary feature. | | | | ------- | ------- | | Type | `Bool` | | Default | `false` | ```swift lines theme={null} import CometChatUIKitSwift let messageList = CometChatMessageList() messageList.enableConversationSummary = true ``` ### set(smartRepliesKeywords:) Sets keywords that trigger smart reply suggestions. ```swift lines theme={null} @discardableResult public func set(smartRepliesKeywords: [String]) -> Self ``` | Parameter | Type | Description | | ---------------------- | ---------- | ----------------------------------- | | `smartRepliesKeywords` | `[String]` | Keywords that trigger smart replies | ```swift lines theme={null} 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. ```swift lines theme={null} @discardableResult public func set(smartRepliesDelayDuration: TimeInterval) -> Self ``` | Parameter | Type | Description | | --------------------------- | -------------- | ------------------------------------------- | | `smartRepliesDelayDuration` | `TimeInterval` | Delay in seconds before showing suggestions | ```swift lines theme={null} 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()` | ```swift lines theme={null} 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()` | ```swift lines theme={null} import CometChatUIKitSwift let messageList = CometChatMessageList() let reactionListConfig = ReactionListConfiguration() reactionListConfig.showUserNames = true messageList.reactionListConfiguration = reactionListConfig ``` ### quickReactionsConfiguration Configuration object for quick reactions. | | | | ------- | ------------------------------- | | Type | `QuickReactionsConfiguration` | | Default | `QuickReactionsConfiguration()` | ```swift lines theme={null} import CometChatUIKitSwift let messageList = CometChatMessageList() let quickReactionsConfig = QuickReactionsConfiguration() quickReactionsConfig.quickReactions = ["👍", "❤️", "😂", "😮", "😢"] messageList.quickReactionsConfiguration = quickReactionsConfig ``` ### messageInformationConfiguration Configuration object for message information display. | | | | ------- | ----------------------------------- | | Type | `MessageInformationConfiguration` | | Default | `MessageInformationConfiguration()` | ```swift lines theme={null} import CometChatUIKitSwift let messageList = CometChatMessageList() let messageInfoConfig = MessageInformationConfiguration() messageInfoConfig.showReadReceipts = true messageInfoConfig.showDeliveryReceipts = true messageList.messageInformationConfiguration = messageInfoConfig ``` *** ## Styling ### Style Hierarchy 1. Global styles (`CometChatMessageList.style`) apply to all instances 2. Instance styles override global for specific instances ### Global Level Styling ```swift lines theme={null} 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 ```swift lines theme={null} 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()` | ```swift lines theme={null} 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()` | ```swift lines theme={null} 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()` | ```swift lines theme={null} 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()` | ```swift lines theme={null} 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()` | ```swift lines theme={null} 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()` | ```swift lines theme={null} 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` | ```swift lines theme={null} 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 | `""` | ```swift lines theme={null} 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"` | ```swift lines theme={null} 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 | `""` | ```swift lines theme={null} 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"` | ```swift lines theme={null} 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` | ```swift lines theme={null} 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` | ```swift lines theme={null} 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` | ```swift lines theme={null} import CometChatUIKitSwift let messageList = CometChatMessageList() messageList.hideReplyMessageOption = true ``` ### hideShareMessageOption Hides the share message option in message actions. | | | | ------- | ------- | | Type | `Bool` | | Default | `false` | ```swift lines theme={null} 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. ```swift lines theme={null} @discardableResult public func set(onLoad: @escaping ([BaseMessage]) -> Void) -> Self ``` | Parameter | Type | Description | | --------- | ------------------------- | ----------------------------- | | `onLoad` | `([BaseMessage]) -> Void` | Callback with loaded messages | ```swift lines theme={null} 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. ```swift lines theme={null} @discardableResult public func set(onEmpty: @escaping () -> Void) -> Self ``` | Parameter | Type | Description | | --------- | ------------ | --------------------------- | | `onEmpty` | `() -> Void` | Callback when list is empty | ```swift lines theme={null} 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 ```swift lines theme={null} 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. ```swift lines theme={null} @discardableResult public func set(datePattern: @escaping (Int?) -> String) -> Self ``` | Parameter | Type | Description | | ------------- | ------------------ | --------------------------------------------- | | `datePattern` | `(Int?) -> String` | Closure that formats timestamp to date string | ```swift lines theme={null} 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. ```swift lines theme={null} @discardableResult public func set(timePattern: @escaping (Int) -> String) -> Self ``` | Parameter | Type | Description | | ------------- | ----------------- | --------------------------------------------- | | `timePattern` | `(Int) -> String` | Closure that formats timestamp to time string | ```swift lines theme={null} 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. ```swift lines theme={null} @discardableResult public func set(dateSeparatorPattern: @escaping (Int?) -> String) -> Self ``` | Parameter | Type | Description | | ---------------------- | ------------------ | ------------------------------------------------------- | | `dateSeparatorPattern` | `(Int?) -> String` | Closure that formats timestamp to date separator string | ```swift lines theme={null} 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 ```swift lines theme={null} let messageList = CometChatMessageList() messageList.set(user: user) messageList.hideReplyInThreadOption = true messageList.hideEditMessageOption = true messageList.hideDeleteMessageOption = true messageList.hideReactionOption = true messageList.hideCopyMessageOption = true ``` ### Disable sounds ```swift lines theme={null} let messageList = CometChatMessageList() messageList.set(user: user) messageList.disableSoundForMessages = true ``` ### Custom empty state ```swift lines theme={null} 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 ```swift lines theme={null} let messageList = CometChatMessageList() messageList.set(user: user) messageList.scrollToBottomOnNewMessages = true ``` ### Hide UI elements ```swift lines theme={null} let messageList = CometChatMessageList() messageList.set(user: user) messageList.hideAvatar = true messageList.hideReceipts = true messageList.hideDateSeparator = true messageList.hideHeaderView = true messageList.hideFooterView = true ``` *** ## Related Components * [Messages](/ui-kit/ios/message-list) - Parent component containing MessageList * [Message Composer](/ui-kit/ios/message-composer) - Send messages in a conversation * [Message Header](/ui-kit/ios/message-header) - Display user/group details * [Message Template](/ui-kit/ios/message-template) - Create custom message bubble templates * [Threaded Messages](/ui-kit/ios/guide-threaded-messages) - Display threaded conversations