Conversations - CometChat Docs

The CometChatConversations component displays a list of all conversations (one-on-one and group chats) for the currently logged-in user. It shows the last message, unread count, typing indicators, and user presence in real-time.

CometChatConversations showing a list of recent conversations with user avatars, last message previews, timestamps, and unread message badges

AI Integration Quick Reference

{
  "component": "CometChatConversations",
  "package": "CometChatUIKitSwift",
  "import": "import CometChatUIKitSwift\nimport CometChatSDK",
  "description": "Displays a list of all conversations for the logged-in user with real-time updates for messages, typing indicators, and presence.",
  "inherits": "UIViewController",
  "primaryOutput": {
    "callback": "onItemClick",
    "type": "(Conversation, IndexPath) -> Void"
  },
  "props": {
    "data": {
      "conversationRequestBuilder": {
        "type": "ConversationRequest.ConversationRequestBuilder?",
        "default": "nil",
        "note": "Custom request builder for filtering conversations"
      }
    },
    "callbacks": {
      "onItemClick": "(Conversation, IndexPath) -> Void",
      "onItemLongClick": "(Conversation, IndexPath) -> Void",
      "onBack": "() -> Void",
      "onSelection": "([Conversation]) -> Void",
      "onError": "(CometChatException) -> Void",
      "onEmpty": "() -> Void",
      "onLoad": "([Conversation]) -> Void"
    },
    "visibility": {
      "hideSearch": { "type": "Bool", "default": false },
      "hideReceipts": { "type": "Bool", "default": false },
      "hideUserStatus": { "type": "Bool", "default": false },
      "hideGroupType": { "type": "Bool", "default": false },
      "hideDeleteConversationOption": { "type": "Bool", "default": false },
      "hideNavigationBar": { "type": "Bool", "default": false },
      "hideBackButton": { "type": "Bool", "default": false }
    },
    "sound": {
      "disableSoundForMessages": { "type": "Bool", "default": false },
      "customSoundForMessages": { "type": "URL?", "default": "nil" }
    },
    "selection": {
      "selectionMode": { "type": "SelectionMode", "default": ".none" }
    },
    "viewSlots": {
      "listItemView": "(Conversation) -> UIView",
      "leadingView": "(Conversation) -> UIView",
      "titleView": "(Conversation) -> UIView",
      "subtitleView": "(Conversation) -> UIView",
      "trailView": "(Conversation) -> UIView",
      "emptyStateView": "UIView  (assign a view; not a closure — inherited from CometChatListBase)",
      "errorStateView": "UIView  (assign a view; not a closure — inherited from CometChatListBase)",
      "loadingView": "UIView  (assign a view; not a closure)"
    },
    "formatting": {
      "datePattern": "(Conversation) -> String",
      "textFormatters": "[CometChatTextFormatter]"
    }
  },
  "events": [
    {
      "name": "ccConversationDelete",
      "payload": "Conversation",
      "description": "Fires when a conversation is deleted"
    }
  ],
  "sdkListeners": [
    "onMessageReceived",
    "onMessageEdited",
    "onMessageDeleted",
    "onTypingStarted",
    "onTypingEnded",
    "onUserOnline",
    "onUserOffline",
    "onGroupMemberJoined",
    "onGroupMemberLeft"
  ],
  "compositionExample": {
    "description": "Conversations list navigating to Messages",
    "components": ["CometChatConversations", "CometChatMessageHeader", "CometChatMessageList", "CometChatMessageComposer"],
    "flow": "User taps conversation → onItemClick fires → push YOUR chat screen (header + list + composer) with the user/group. v5 ships no composite component."
  },
  "types": {
    "Conversation": {
      "conversationId": "String?",
      "conversationType": "ConversationType",
      "conversationWith": "AppEntity?",
      "lastMessage": "BaseMessage?",
      "unreadMessageCount": "Int"
    },
    "ConversationType": {
      "user": "One-on-one conversations only",
      "group": "Group conversations only",
      "none": "No type filter",
      "_note": "Set with setConversationType(conversationType:), not set(conversationType:). Omit it entirely to get both 1:1s and groups."
    }
  }
}

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

Where It Fits

CometChatConversations serves as the main entry point for chat functionality. It displays all conversations; on selection you push your own chat screen, composed from CometChatMessageHeader + CometChatMessageList + CometChatMessageComposer (see Conversation List + Message View). The UI Kit ships no composite/all-in-one messages component.

import UIKit
import CometChatUIKitSwift
import CometChatSDK

class ChatListViewController: UIViewController {
    
    private var conversationsController: CometChatConversations!
    
    override func viewDidLoad() {
        super.viewDidLoad()
        setupConversations()
    }
    
    private func setupConversations() {
        conversationsController = CometChatConversations()
        
        // Handle conversation selection - navigate to messages
        conversationsController.set(onItemClick: { [weak self] conversation, indexPath in
            self?.openMessages(for: conversation)
        })
        
        navigationController?.pushViewController(conversationsController, animated: true)
    }
    
    private func openMessages(for conversation: Conversation) {
        let messagesVC = MessagesVC()   // your own VC — see /ui-kit/ios/ios-conversation
        
        messagesVC.user  = conversation.conversationWith as? User
        messagesVC.group = conversation.conversationWith as? Group
        
        navigationController?.pushViewController(messagesVC, animated: true)
    }
}

CometChatConversations showing integration flow with conversation list navigating to messages screen

Minimal Render

import CometChatUIKitSwift

let conversations = CometChatConversations()
navigationController?.pushViewController(conversations, animated: true)

Filtering

Use ConversationRequest.ConversationRequestBuilder to filter which conversations appear in the list. The builder pattern allows chaining multiple filter conditions.

import CometChatUIKitSwift
import CometChatSDK

// Create a custom request builder
// Omit setConversationType to get BOTH 1:1s and groups — that is the default.
let requestBuilder = ConversationRequest.ConversationRequestBuilder(limit: 30)

let conversations = CometChatConversations(conversationRequestBuilder: requestBuilder)

Filter Recipes

Recipe	Code
Show only one-on-one chats	`.setConversationType(conversationType: .user)`
Show only group chats	`.setConversationType(conversationType: .group)`
Filter by tags	`.withTags(true).set(tags: ["support", "sales"])`
Limit results	`ConversationRequestBuilder(limit: 20)`
Include user/group tags	`.withUserAndGroupTags(true)`

Actions and Events

Callback Props

onItemClick

Fires when a user taps on a conversation. Use this to navigate to the messages screen.

import CometChatUIKitSwift
import CometChatSDK

let conversations = CometChatConversations()

conversations.set(onItemClick: { [weak self] conversation, indexPath in
    guard let self = self else { return }
    
    let messagesVC = MessagesVC()   // your own VC — see /ui-kit/ios/ios-conversation
    
    messagesVC.user  = conversation.conversationWith as? User
    messagesVC.group = conversation.conversationWith as? Group
    
    self.navigationController?.pushViewController(messagesVC, animated: true)
})

onItemLongClick

Fires when a user long-presses on a conversation. Use this to show additional options like delete or mute.

import CometChatUIKitSwift
import CometChatSDK

let conversations = CometChatConversations()

conversations.set(onItemLongClick: { [weak self] conversation, indexPath in
    guard let self = self else { return }
    
    let alert = UIAlertController(title: "Options", message: nil, preferredStyle: .actionSheet)
    
    alert.addAction(UIAlertAction(title: "Delete", style: .destructive) { [weak self] _ in
        self?.deleteConversation(conversation)
    })
    
    alert.addAction(UIAlertAction(title: "Cancel", style: .cancel))
    self.present(alert, animated: true)
})

// Helper method to delete conversation using SDK
private func deleteConversation(_ conversation: Conversation) {
    CometChat.deleteConversation(
        conversationWith: conversation.conversationWith?.uid ?? "",
        conversationType: conversation.conversationType
    ) { success in
        print("Conversation deleted successfully")
    } onError: { error in
        print("Delete failed: \(error?.errorDescription ?? "")")
    }
}

onBack

Fires when the back button is pressed. Use this for custom navigation handling.

import CometChatUIKitSwift

let conversations = CometChatConversations()

conversations.set(onBack: { [weak self] in
    self?.navigationController?.popViewController(animated: true)
})

onSelection

Fires when conversations are selected in selection mode. Returns the list of selected conversations.

import CometChatUIKitSwift
import CometChatSDK

let conversations = CometChatConversations()
conversations.selectionMode = .multiple

conversations.set(onSelection: { [weak self] selectedConversations in
    print("Selected \(selectedConversations.count) conversations")
})

onError

Fires when an error occurs while loading conversations.

import CometChatUIKitSwift

let conversations = CometChatConversations()

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

onEmpty

Fires when the conversation list is empty.

import CometChatUIKitSwift

let conversations = CometChatConversations()

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

onLoad

Fires when conversations are successfully loaded.

import CometChatUIKitSwift
import CometChatSDK

let conversations = CometChatConversations()

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

Actions Reference

Method	Description	Example
`set(onItemClick:)`	Triggered when a conversation is tapped	Navigate to messages
`set(onItemLongClick:)`	Triggered on long press	Show options menu
`set(onBack:)`	Triggered when back button is pressed	Custom navigation
`set(onSelection:)`	Triggered in selection mode	Multi-select conversations
`set(onError:)`	Triggered when an error occurs	Show error alert
`set(onEmpty:)`	Triggered when list is empty	Show empty state
`set(onLoad:)`	Triggered when conversations load	Analytics tracking

Global UI Events

Event	Fires when	Payload
`ccConversationDelete`	A conversation is deleted	`Conversation`

import CometChatUIKitSwift
import CometChatSDK

class MyViewController: UIViewController, CometChatConversationEventListener {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        CometChatConversationEvents.addListener("my-listener", self)
    }
    
    override func viewWillDisappear(_ animated: Bool) {
        super.viewWillDisappear(animated)
        CometChatConversationEvents.removeListener("my-listener")
    }
    
    func ccConversationDelete(conversation: Conversation) {
        print("Conversation deleted: \(conversation.conversationId ?? "")")
    }
}

SDK Events (Real-Time, Automatic)

SDK Listener	Internal behavior
`onMessageReceived`	Updates last message and moves conversation to top
`onMessageEdited`	Updates last message preview if edited message is latest
`onMessageDeleted`	Updates last message preview if deleted message was latest
`onTypingStarted`	Shows typing indicator for the conversation
`onTypingEnded`	Hides typing indicator for the conversation
`onUserOnline`	Updates online status indicator for user conversations
`onUserOffline`	Updates offline status indicator for user conversations
`onGroupMemberJoined`	Updates group member count
`onGroupMemberLeft`	Updates group member count

Pinning Conversations

Available since v5.1.22 A pinned conversation sits at the top of the list with a pin indicator on the row, and holds that position as new messages arrive in other chats. A personal pin is private to the logged-in user — nobody else sees it — and syncs to that user’s other devices.

Two gates, both required. Pin Conversation needs the features.ux.conversations.pinned.enabled app setting mapped for your app, and your own opt-in via enablePinConversation. With either missing the swipe action never appears. The kit reads the app setting through CometChat.isPinConversationEnabled().

import CometChatUIKitSwift

let conversations = CometChatConversations()
conversations.enablePinConversation = true      // off by default

Pinning applies immediately; unpinning asks for confirmation first. Hide the action on a single list with hidePinConversationOption while it stays available elsewhere.

Admin Pins

An app can also pin a conversation for everyone. A system pin sorts above every personal pin, and is not the user’s to remove — the kit does not offer the unpin affordance on those rows at all. To reflect the same distinction in a view of your own, read the two properties the SDK exposes on Conversation:

import CometChatSDK

// `pinnedAt` uses a 0 sentinel, so presence — not `> 0` — is the pinned test.
let isPinned = conversation.pinnedAt != 0

// An admin/global pin. A user cannot unpin one, so hide or disable your unpin control.
let isSystemPinned = isPinned && conversation.pinnedBy == "app_system"

The UI Kit has no public helper for this yet — unlike the React Native kit’s isSystemPinnedConversation() — so the "app_system" sentinel has to be compared directly for now.

Errors

A failed pin surfaces as a toast. PinConversationErrorCodes names the codes the backend emits, so you can match them in your own handling:

Code	Meaning
`ERR_PINNED_CONVERSATIONS_LIMIT_EXCEEDED`	The user is at the per-user pinned cap. The real cap rides in `errorParams` — never hard-code it.
`ERR_CONVERSATION_NOT_ACCESSIBLE`	No conversation row yet (never messaged), or deleted-for-me.
`ERR_PERMISSION_DENIED`	RBAC denial.
`ERR_BAD_REQUEST`	Invalid `pinnedBy` filter or malformed body.

Custom View Slots

Slot	Signature	Replaces
`listItemView`	`(Conversation) -> UIView`	Entire conversation row
`leadingView`	`(Conversation) -> UIView`	Avatar / left section
`titleView`	`(Conversation) -> UIView`	Name / title text
`subtitleView`	`(Conversation) -> UIView`	Last message preview
`trailView`	`(Conversation) -> UIView`	Right side (time, badge)
`emptyStateView`	`UIView`	Empty state display — assign a view, not a closure
`errorStateView`	`UIView`	Error state display — assign a view, not a closure
`loadingView`	`UIView`	Loading state display — assign a view, not a closure

listItemView

Replace the entire conversation row with a custom design.

import UIKit
import CometChatUIKitSwift
import CometChatSDK

let conversations = CometChatConversations()

conversations.set(listItemView: { conversation in
    let customView = CustomConversationCell()
    customView.configure(with: conversation)
    return customView
})

// CustomConversationCell.swift
class CustomConversationCell: UIView {
    
    private let avatarView = CometChatAvatar(image: UIImage())
    private let nameLabel = UILabel()
    private let messageLabel = UILabel()
    private let timeLabel = UILabel()
    
    override init(frame: CGRect) {
        super.init(frame: frame)
        setupUI()
    }
    
    required init?(coder: NSCoder) {
        fatalError("init(coder:) has not been implemented")
    }
    
    private func setupUI() {
        nameLabel.font = UIFont.systemFont(ofSize: 16, weight: .semibold)
        messageLabel.font = UIFont.systemFont(ofSize: 14)
        messageLabel.textColor = UIColor.secondaryLabel
        timeLabel.font = UIFont.systemFont(ofSize: 12)
        timeLabel.textColor = UIColor.tertiaryLabel
        
        // Add subviews and constraints...
    }
    
    func configure(with conversation: Conversation) {
        if let user = conversation.conversationWith as? User {
            nameLabel.text = user.name
            avatarView.setAvatar(avatarUrl: user.avatar, with: user.name ?? "")
        } else if let group = conversation.conversationWith as? Group {
            nameLabel.text = group.name
            avatarView.setAvatar(avatarUrl: group.icon, with: group.name ?? "")
        }
        
        if let textMessage = conversation.lastMessage as? TextMessage {
            messageLabel.text = textMessage.text
        }
    }
}

subtitleView

Customize just the subtitle area below the conversation name.

import UIKit
import CometChatUIKitSwift
import CometChatSDK

let conversations = CometChatConversations()

conversations.set(subtitleView: { conversation in
    let label = UILabel()
    label.font = UIFont.systemFont(ofSize: 13)
    label.textColor = UIColor.secondaryLabel
    
    if let textMessage = conversation.lastMessage as? TextMessage {
        label.text = textMessage.text
    } else if conversation.lastMessage is MediaMessage {
        label.text = "📷 Photo"
    } else {
        label.text = "No messages yet"
    }
    
    return label
})

leadingView

Customize the avatar / left section of the conversation row.


Signature	`(Conversation) -> UIView`
Replaces	Avatar / left section

import UIKit
import CometChatUIKitSwift
import CometChatSDK

let conversations = CometChatConversations()

conversations.set(leadingView: { conversation in
    let containerView = UIView()
    containerView.translatesAutoresizingMaskIntoConstraints = false
    
    let avatarView = CometChatAvatar(image: UIImage())
    avatarView.translatesAutoresizingMaskIntoConstraints = false
    
    if let user = conversation.conversationWith as? User {
        avatarView.setAvatar(avatarUrl: user.avatar, with: user.name ?? "")
    } else if let group = conversation.conversationWith as? Group {
        avatarView.setAvatar(avatarUrl: group.icon, with: group.name ?? "")
    }
    
    containerView.addSubview(avatarView)
    
    // Add online indicator
    let statusIndicator = UIView()
    statusIndicator.backgroundColor = UIColor.systemGreen
    statusIndicator.layer.cornerRadius = 6
    statusIndicator.translatesAutoresizingMaskIntoConstraints = false
    containerView.addSubview(statusIndicator)
    
    NSLayoutConstraint.activate([
        avatarView.widthAnchor.constraint(equalToConstant: 48),
        avatarView.heightAnchor.constraint(equalToConstant: 48),
        avatarView.centerXAnchor.constraint(equalTo: containerView.centerXAnchor),
        avatarView.centerYAnchor.constraint(equalTo: containerView.centerYAnchor),
        statusIndicator.widthAnchor.constraint(equalToConstant: 12),
        statusIndicator.heightAnchor.constraint(equalToConstant: 12),
        statusIndicator.trailingAnchor.constraint(equalTo: avatarView.trailingAnchor),
        statusIndicator.bottomAnchor.constraint(equalTo: avatarView.bottomAnchor)
    ])
    
    return containerView
})

titleView

Customize the title area that displays the conversation name.


Signature	`(Conversation) -> UIView`
Replaces	Name / title text area

import UIKit
import CometChatUIKitSwift
import CometChatSDK

let conversations = CometChatConversations()

conversations.set(titleView: { conversation in
    let stackView = UIStackView()
    stackView.axis = .horizontal
    stackView.spacing = 8
    stackView.alignment = .center
    
    // Name label
    let nameLabel = UILabel()
    nameLabel.font = UIFont.systemFont(ofSize: 16, weight: .semibold)
    nameLabel.textColor = UIColor.label
    
    if let user = conversation.conversationWith as? User {
        nameLabel.text = user.name
    } else if let group = conversation.conversationWith as? Group {
        nameLabel.text = group.name
    }
    
    stackView.addArrangedSubview(nameLabel)
    
    // Add verified badge for specific users
    if let user = conversation.conversationWith as? User,
       user.metadata?["verified"] as? Bool == true {
        let badgeImage = UIImageView(image: UIImage(systemName: "checkmark.seal.fill"))
        badgeImage.tintColor = UIColor.systemBlue
        badgeImage.widthAnchor.constraint(equalToConstant: 16).isActive = true
        badgeImage.heightAnchor.constraint(equalToConstant: 16).isActive = true
        stackView.addArrangedSubview(badgeImage)
    }
    
    return stackView
})

trailView

Customize the right side of the conversation row (time, unread badge). The setter is set(trailView:), which takes a closure receiving the Conversation.

import UIKit
import CometChatUIKitSwift
import CometChatSDK

let conversations = CometChatConversations()

conversations.set(trailView: { conversation in
    let stackView = UIStackView()
    stackView.axis = .vertical
    stackView.alignment = .trailing
    stackView.spacing = 4
    
    // Time label
    let timeLabel = UILabel()
    timeLabel.font = UIFont.systemFont(ofSize: 12)
    timeLabel.textColor = UIColor.tertiaryLabel
    
    if let sentAt = conversation.lastMessage?.sentAt {
        let date = Date(timeIntervalSince1970: TimeInterval(sentAt))
        let formatter = DateFormatter()
        formatter.dateFormat = "h:mm a"
        timeLabel.text = formatter.string(from: date)
    }
    
    stackView.addArrangedSubview(timeLabel)
    
    // Unread badge
    if conversation.unreadMessageCount > 0 {
        let badge = UILabel()
        badge.text = "\(conversation.unreadMessageCount)"
        badge.font = UIFont.systemFont(ofSize: 12, weight: .bold)
        badge.textColor = UIColor.white
        badge.backgroundColor = UIColor.systemRed
        badge.textAlignment = .center
        badge.layer.cornerRadius = 10
        badge.clipsToBounds = true
        badge.widthAnchor.constraint(greaterThanOrEqualToConstant: 20).isActive = true
        badge.heightAnchor.constraint(equalToConstant: 20).isActive = true
        stackView.addArrangedSubview(badge)
    }
    
    return stackView
})

Styling

Style Hierarchy

Global styles (CometChatConversation.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 CometChatConversations instances
CometChatConversation.style.backgroundColor = UIColor.systemBackground
CometChatConversation.style.titleFont = UIFont.systemFont(ofSize: 17, weight: .bold)
CometChatConversation.style.titleColor = UIColor.label
CometChatConversation.style.listItemTitleTextColor = UIColor.label
CometChatConversation.style.listItemSubTitleTextColor = UIColor.secondaryLabel

// Custom avatar style
let avatarStyle = AvatarStyle()
avatarStyle.backgroundColor = UIColor(red: 0.41, green: 0.32, blue: 0.84, alpha: 1.0)
avatarStyle.cornerRadius = 8
CometChatConversation.style.avatarStyle = avatarStyle

// Custom badge style for unread count
let badgeStyle = BadgeStyle()
badgeStyle.backgroundColor = UIColor.systemRed
badgeStyle.cornerRadius = CometChatCornerStyle(cornerRadius: 10)
CometChatConversation.style.badgeStyle = badgeStyle

Instance Level Styling

import UIKit
import CometChatUIKitSwift

// Create a custom style for a specific instance
var customStyle = ConversationsStyle()
customStyle.backgroundColor = UIColor(red: 0.95, green: 0.95, blue: 0.97, alpha: 1.0)
customStyle.titleColor = UIColor(red: 0.2, green: 0.2, blue: 0.2, alpha: 1.0)
customStyle.listItemBackground = UIColor.white
customStyle.listItemCornerRadius = CometChatCornerStyle(cornerRadius: 12)

let conversations = CometChatConversations()
conversations.style = customStyle

CometChatConversations with custom styling applied showing customized background, colors, and list item appearance

Key Style Properties

Property	Type	Default	Description
`backgroundColor`	`UIColor`	`CometChatTheme.backgroundColor01`	Background color of the list
`titleFont`	`UIFont?`	`CometChatTypography.setFont(size: 17, weight: .bold)`	Font for the navigation title
`titleColor`	`UIColor?`	`CometChatTheme.textColorPrimary`	Color for the navigation title
`listItemTitleTextColor`	`UIColor`	`CometChatTheme.textColorPrimary`	Color for conversation names
`listItemTitleFont`	`UIFont`	`CometChatTypography.Heading4.medium`	Font for conversation names
`listItemSubTitleTextColor`	`UIColor`	`CometChatTheme.textColorSecondary`	Color for last message preview
`listItemSubTitleFont`	`UIFont`	`CometChatTypography.Body.regular`	Font for last message preview
`listItemBackground`	`UIColor`	`.clear`	Background color for list items
`listItemCornerRadius`	`CometChatCornerStyle`	`CometChatCornerStyle(cornerRadius: 0)`	Corner radius for list items
`borderWidth`	`CGFloat`	`0`	Border width for the component
`borderColor`	`UIColor`	`.clear`	Border color for the component

Customization Matrix

What to change	Where	Property/API	Example
Background color	Style	`backgroundColor`	`UIColor.systemBackground`
Title appearance	Style	`titleFont`, `titleColor`	`UIFont.boldSystemFont(ofSize: 18)`
List item look	Style	`listItemBackground`	`UIColor(white: 0.95, alpha: 1.0)`
Unread badge	Style	`badgeStyle`	`BadgeStyle()` with custom colors
Avatar appearance	Style	`avatarStyle`	`AvatarStyle()` with custom radius
Hide search	Property	`hideSearch`	`conversations.hideSearch = true`
Hide receipts	Property	`hideReceipts`	`conversations.hideReceipts = true`
Custom row	View Slot	`set(listItemView:)`	See Custom View Slots section

Methods

Swipe Action Methods

set(options:)

Sets custom swipe actions for conversation list items, replacing the default options.

@discardableResult
public func set(options: ((_ conversation: Conversation?) -> [CometChatConversationOption])?) -> Self

Parameter	Type	Description
`options`	`((Conversation?) -> [CometChatConversationOption])?`	Closure that returns an array of swipe action options for a conversation

import UIKit
import CometChatUIKitSwift
import CometChatSDK

let conversations = CometChatConversations()

conversations.set(options: { conversation in
    var options = [CometChatConversationOption]()
    
    // Add delete option
    let deleteOption = CometChatConversationOption(
        id: "delete",
        title: "Delete",
        icon: UIImage(systemName: "trash"),
        backgroundColor: .systemRed
    ) { conv in
        // Handle delete action
        print("Delete conversation: \(conv?.conversationId ?? "")")
    }
    options.append(deleteOption)
    
    return options
})

add(options:)

Adds additional swipe actions to the existing default options.

@discardableResult
public func add(options: ((_ conversation: Conversation?) -> [CometChatConversationOption])?) -> Self

Parameter	Type	Description
`options`	`((Conversation?) -> [CometChatConversationOption])?`	Closure that returns additional swipe action options to append

import UIKit
import CometChatUIKitSwift
import CometChatSDK

let conversations = CometChatConversations()

conversations.add(options: { conversation in
    var options = [CometChatConversationOption]()
    
    // Add mute option
    let muteOption = CometChatConversationOption(
        id: "mute",
        title: "Mute",
        icon: UIImage(systemName: "bell.slash"),
        backgroundColor: .systemOrange
    ) { conv in
        print("Mute conversation: \(conv?.conversationId ?? "")")
    }
    options.append(muteOption)
    
    return options
})

Data Manipulation Methods

insert(conversation:at:)

Inserts a conversation at a specific index in the list.

public func insert(conversation: Conversation, at index: Int)

Parameter	Type	Description
`conversation`	`Conversation`	The conversation to insert
`index`	`Int`	The position at which to insert the conversation

import CometChatUIKitSwift
import CometChatSDK

let conversations = CometChatConversations()

// Insert a conversation at the top of the list
if let conversation = someConversation {
    conversations.insert(conversation: conversation, at: 0)
}

getSelectedConversations()

Returns the list of currently selected conversations when in selection mode.

public func getSelectedConversations() -> [Conversation]

import CometChatUIKitSwift
import CometChatSDK

let conversations = CometChatConversations()
conversations.selectionMode = .multiple

// Get selected conversations
let selectedConversations = conversations.getSelectedConversations()
print("Selected \(selectedConversations.count) conversations")

getConversationList()

Returns the complete list of conversations currently displayed.

public func getConversationList() -> [Conversation]

import CometChatUIKitSwift
import CometChatSDK

let conversations = CometChatConversations()

// Get all conversations in the list
let allConversations = conversations.getConversationList()
print("Total conversations: \(allConversations.count)")

Connection Methods

connect()

Manually establishes the WebSocket connection for real-time updates. Use this when you need to reconnect after calling disconnect().

public func connect()

import CometChatUIKitSwift

let conversations = CometChatConversations()

// Reconnect to receive real-time updates
conversations.connect()

disconnect()

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

public func disconnect()

import CometChatUIKitSwift

let conversations = CometChatConversations()

// Disconnect when view is not visible
conversations.disconnect()

// Later, reconnect when view becomes visible again
conversations.connect()

Text Formatter Methods

set(textFormatters:)

Sets custom text formatters for processing and displaying message text in conversation subtitles.

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

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

import CometChatUIKitSwift

let conversations = CometChatConversations()

// Mentions are formatted by CometChatMentionsFormatter, a CometChatTextFormatter subclass.
// Subclass CometChatTextFormatter yourself for any other formatting you need.
let mentionFormatter = CometChatMentionsFormatter()

conversations.set(textFormatters: [mentionFormatter])

Props

All props are optional. Sorted alphabetically.

avatarStyle

Customizes the appearance of avatars in conversation list items.


Type	`AvatarStyle`
Default	`AvatarStyle()`

import CometChatUIKitSwift

let conversations = CometChatConversations()

let avatarStyle = AvatarStyle()
avatarStyle.backgroundColor = UIColor.systemBlue
avatarStyle.cornerRadius = CometChatCornerStyle(cornerRadius: 8)
avatarStyle.borderWidth = 1
avatarStyle.borderColor = UIColor.systemGray4

conversations.avatarStyle = avatarStyle

badgeStyle

Customizes the appearance of unread message count badges.


Type	`BadgeStyle`
Default	`BadgeStyle()`

import CometChatUIKitSwift

let conversations = CometChatConversations()

let badgeStyle = BadgeStyle()
badgeStyle.backgroundColor = UIColor.systemRed
badgeStyle.textColor = UIColor.white
badgeStyle.textFont = UIFont.systemFont(ofSize: 12, weight: .bold)
badgeStyle.cornerRadius = CometChatCornerStyle(cornerRadius: 10)

conversations.badgeStyle = badgeStyle

conversationRequestBuilder

Custom request builder for filtering which conversations appear.


Type	`ConversationRequest.ConversationRequestBuilder?`
Default	`nil`

dateStyle

Customizes the appearance of date/time labels in conversation list items.


Type	`DateStyle`
Default	`DateStyle()`

import CometChatUIKitSwift

let conversations = CometChatConversations()

let dateStyle = DateStyle()
dateStyle.textColor = UIColor.secondaryLabel
dateStyle.textFont = UIFont.systemFont(ofSize: 12)

conversations.dateStyle = dateStyle

dateTimeFormatter

Custom formatter for date/time display in conversation list items.


Type	`CometChatDateTimeFormatter?`
Default	`nil`

import CometChatUIKitSwift

let conversations = CometChatConversations()

let dateTimeFormatter = CometChatDateTimeFormatter()
dateTimeFormatter.todayFormat = "h:mm a"
dateTimeFormatter.yesterdayFormat = "'Yesterday'"
dateTimeFormatter.otherFormat = "MMM d"

conversations.dateTimeFormatter = dateTimeFormatter

customSoundForMessages

Custom sound URL for new message notifications.


Type	`URL?`
Default	`nil`

disableSoundForMessages

Disables notification sounds for new messages.


Type	`Bool`
Default	`false`

disableTyping

Disables typing indicators in the conversation list.


Type	`Bool`
Default	`false`

import CometChatUIKitSwift

let conversations = CometChatConversations()
conversations.disableTyping = true

enablePinConversation

Available since v5.1.22 Adds the Pin / Unpin swipe action to each row. Off by default — see Pinning Conversations for the feature, including the app setting it also requires.


Type	`Bool`
Default	`false`

import CometChatUIKitSwift

let conversations = CometChatConversations()
conversations.enablePinConversation = true

hideBackButton

Hides the back button in the navigation bar.


Type	`Bool`
Default	`false`

hideDeleteConversationOption

Hides the delete option in conversation actions.


Type	`Bool`
Default	`false`

hideGroupType

Hides the public/private group type icons.


Type	`Bool`
Default	`false`

hideNavigationBar

Hides the entire navigation bar.


Type	`Bool`
Default	`false`

hidePinConversationOption

Available since v5.1.22 Hides the Pin / Unpin swipe action on one list while the feature stays on elsewhere. ANDed with enablePinConversation and the app setting — see Pinning Conversations.


Type	`Bool`
Default	`false`

import CometChatUIKitSwift

let conversations = CometChatConversations()
conversations.hidePinConversationOption = true

hideReceipts

Hides read/delivered receipt indicators.


Type	`Bool`
Default	`false`

hideSearch

Hides the search bar.


Type	`Bool`
Default	`false`

hideUserStatus

Hides online/offline status indicators.


Type	`Bool`
Default	`false`

onSearchClick

Callback triggered when the search button is clicked.


Type	`(() -> Void)?`
Default	`nil`

import CometChatUIKitSwift

let conversations = CometChatConversations()

conversations.onSearchClick = { [weak self] in
    // Handle search button click
    self?.presentSearchViewController()
}

privateGroupIcon

Custom icon for private group conversations.


Type	`UIImage?`
Default	`nil`

import CometChatUIKitSwift

let conversations = CometChatConversations()
conversations.privateGroupIcon = UIImage(systemName: "lock.fill")

protectedGroupIcon

Custom icon for password-protected group conversations.


Type	`UIImage?`
Default	`nil`

import CometChatUIKitSwift

let conversations = CometChatConversations()
conversations.protectedGroupIcon = UIImage(systemName: "lock.shield.fill")

receiptStyle

Customizes the appearance of message receipt indicators (sent, delivered, read).


Type	`ReceiptStyle`
Default	`ReceiptStyle()`

import CometChatUIKitSwift

let conversations = CometChatConversations()

let receiptStyle = ReceiptStyle()
receiptStyle.sentIconTint = UIColor.systemGray
receiptStyle.deliveredIconTint = UIColor.systemGray
receiptStyle.readIconTint = UIColor.systemBlue

conversations.receiptStyle = receiptStyle

selectionMode

Sets the selection mode for multi-select functionality.


Type	`SelectionMode`
Default	`.none`

statusIndicatorStyle

Customizes the appearance of online/offline status indicators.


Type	`StatusIndicatorStyle`
Default	`StatusIndicatorStyle()`

import CometChatUIKitSwift

let conversations = CometChatConversations()

let statusIndicatorStyle = StatusIndicatorStyle()
statusIndicatorStyle.backgroundColor = UIColor.systemGreen
statusIndicatorStyle.borderWidth = 2
statusIndicatorStyle.borderColor = UIColor.white

conversations.statusIndicatorStyle = statusIndicatorStyle

textFormatters

Array of text formatters for customizing message text display.


Type	`[CometChatTextFormatter]`
Default	`[]`

typingIndicatorStyle

Customizes the appearance of typing indicators in conversation list items.


Type	`TypingIndicatorStyle`
Default	`TypingIndicatorStyle()`

import CometChatUIKitSwift

let conversations = CometChatConversations()

let typingIndicatorStyle = TypingIndicatorStyle()
typingIndicatorStyle.textColor = UIColor.systemGray
typingIndicatorStyle.textFont = UIFont.italicSystemFont(ofSize: 14)

conversations.typingIndicatorStyle = typingIndicatorStyle

Events

Event	Payload	Fires when
`ccConversationDelete`	`Conversation`	A conversation is deleted from the list

Date Time Formatter

Customize how timestamps appear in the conversation list using the datePattern callback.

Global Level Formatting

import CometChatUIKitSwift

// Set a global date pattern for all conversations instances
CometChatConversations.datePattern = { conversation in
    guard let sentAt = conversation.lastMessage?.sentAt else { return "" }
    
    let date = Date(timeIntervalSince1970: TimeInterval(sentAt))
    let formatter = DateFormatter()
    
    if Calendar.current.isDateInToday(date) {
        formatter.dateFormat = "h:mm a"
    } else if Calendar.current.isDateInYesterday(date) {
        return "Yesterday"
    } else {
        formatter.dateFormat = "MMM d"
    }
    
    return formatter.string(from: date)
}

Instance Level Formatting

import CometChatUIKitSwift

let conversations = CometChatConversations()

conversations.set(datePattern: { conversation in
    guard let sentAt = conversation.lastMessage?.sentAt else { return "" }
    
    let date = Date(timeIntervalSince1970: TimeInterval(sentAt))
    let formatter = DateFormatter()
    
    if Calendar.current.isDateInToday(date) {
        formatter.dateFormat = "HH:mm"  // 24-hour format
    } else if Calendar.current.isDateInYesterday(date) {
        return "Yesterday"
    } else if Calendar.current.isDate(date, equalTo: Date(), toGranularity: .weekOfYear) {
        formatter.dateFormat = "EEEE"  // Day name
    } else {
        formatter.dateFormat = "dd/MM/yy"
    }
    
    return formatter.string(from: date)
})

Available Formatters

Formatter	Purpose	Default Format
`datePattern`	Format for all timestamps	`h:mm a` for today, `MMM d` for older

Common Customizations

import CometChatUIKitSwift

let conversations = CometChatConversations()

// 24-hour time format
conversations.set(datePattern: { conversation in
    guard let sentAt = conversation.lastMessage?.sentAt else { return "" }
    let date = Date(timeIntervalSince1970: TimeInterval(sentAt))
    let formatter = DateFormatter()
    formatter.dateFormat = "HH:mm"
    return formatter.string(from: date)
})

// Relative time (e.g., "2h ago")
conversations.set(datePattern: { conversation in
    guard let sentAt = conversation.lastMessage?.sentAt else { return "" }
    let date = Date(timeIntervalSince1970: TimeInterval(sentAt))
    let formatter = RelativeDateTimeFormatter()
    formatter.unitsStyle = .abbreviated
    return formatter.localizedString(for: date, relativeTo: Date())
})

Mention Configuration

Configure how @all mentions appear in conversation list items. When a message contains an @all mention, the conversation subtitle displays the mention with a customizable label.

setMentionAllLabel

Sets a custom label for @all mentions displayed in conversation list items.

@discardableResult
public func setMentionAllLabel(_ id: String, _ label: String) -> Self

Parameter	Type	Description
`id`	`String`	The identifier for the @all mention (typically “all”)
`label`	`String`	The display text shown to users when @all is mentioned

import CometChatUIKitSwift

let conversations = CometChatConversations()

// Set a custom label for @all mentions
conversations.setMentionAllLabel("all", "Everyone")

import UIKit
import CometChatUIKitSwift
import CometChatSDK

class MentionConfiguredViewController: UIViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        let conversations = CometChatConversations()
            .setMentionAllLabel("all", "Team Members")
            .set(onItemClick: { [weak self] conversation, indexPath in
                self?.openMessages(for: conversation)
            })
        
        navigationController?.pushViewController(conversations, animated: true)
    }
    
    private func openMessages(for conversation: Conversation) {
        let messagesVC = MessagesVC()   // your own VC — see /ui-kit/ios/ios-conversation
        
        messagesVC.user  = conversation.conversationWith as? User
        messagesVC.group = conversation.conversationWith as? Group
        
        navigationController?.pushViewController(messagesVC, animated: true)
    }
}

Common Patterns

Tab bar integration

Full implementation with tab bar showing CometChatConversations in a real app:

import UIKit
import CometChatUIKitSwift
import CometChatSDK

class MainTabBarController: UITabBarController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        setupTabs()
    }
    
    private func setupTabs() {
        // Conversations Tab
        let conversationsVC = ConversationsContainerViewController()
        conversationsVC.tabBarItem = UITabBarItem(
            title: "Chats",
            image: UIImage(systemName: "message"),
            selectedImage: UIImage(systemName: "message.fill")
        )
        
        // Users Tab
        let usersVC = UINavigationController(rootViewController: CometChatUsers())
        usersVC.tabBarItem = UITabBarItem(
            title: "Users",
            image: UIImage(systemName: "person.2"),
            selectedImage: UIImage(systemName: "person.2.fill")
        )
        
        // Groups Tab
        let groupsVC = UINavigationController(rootViewController: CometChatGroups())
        groupsVC.tabBarItem = UITabBarItem(
            title: "Groups",
            image: UIImage(systemName: "person.3"),
            selectedImage: UIImage(systemName: "person.3.fill")
        )
        
        viewControllers = [conversationsVC, usersVC, groupsVC]
    }
}

class ConversationsContainerViewController: UINavigationController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        let conversations = CometChatConversations()
        
        // Navigate to messages on tap
        conversations.set(onItemClick: { [weak self] conversation, _ in
            let messagesVC = MessagesVC()   // your own VC — see /ui-kit/ios/ios-conversation
            
            if let user = conversation.conversationWith as? User {
                messagesVC.set(user: user)
            } else if let group = conversation.conversationWith as? Group {
                messagesVC.set(group: group)
            }
            
            self?.pushViewController(messagesVC, animated: true)
        })
        
        setViewControllers([conversations], animated: false)
    }
}

Custom empty state with CTA

The empty state is a UIView you assign, not a closure — emptyStateView is inherited from CometChatListBase. Build the view first, then set it (set(emptyView:) is the equivalent builder form).

let conversations = CometChatConversations()

let emptyView = UIView()

let label = UILabel()
label.text = "No conversations yet"
label.textAlignment = .center
label.textColor = .secondaryLabel

let button = UIButton(type: .system)
button.setTitle("Start a conversation", for: .normal)
button.addTarget(self, action: #selector(startNewConversation), for: .touchUpInside)

// Add subviews and constraints to emptyView...

conversations.emptyStateView = emptyView          // or: conversations.set(emptyView: emptyView)

// Want to keep the built-in empty state and just retitle it?
conversations.emptyStateTitleText = "No conversations yet"
conversations.emptyStateSubTitleText = "Start a chat to see it here"

Hide all chrome — minimal list

let conversations = CometChatConversations()
conversations.hideReceipts = true
conversations.hideUserStatus = true
conversations.hideGroupType = true
conversations.hideDeleteConversationOption = true

Filter by conversation type

// Only user conversations
let userOnlyBuilder = ConversationRequest.ConversationRequestBuilder(limit: 30)
    .setConversationType(conversationType: .user)

let conversations = CometChatConversations(conversationRequestBuilder: userOnlyBuilder)

// Only group conversations
let groupOnlyBuilder = ConversationRequest.ConversationRequestBuilder(limit: 30)
    .setConversationType(conversationType: .group)

let groupConversations = CometChatConversations(conversationRequestBuilder: groupOnlyBuilder)

Messages - Display messages in a conversation
Users - List all users to start new conversations
Groups - List all groups
Message Composer - Send messages in a conversation
Conversation With Messages - Combined conversations and messages view

​Where It Fits

​Minimal Render

​Filtering

​Filter Recipes

​Actions and Events

​Callback Props

​onItemClick

​onItemLongClick

​onBack

​onSelection

​onError

​onEmpty

​onLoad

​Actions Reference

​Global UI Events

​SDK Events (Real-Time, Automatic)

​Pinning Conversations

​Admin Pins

​Errors

​Custom View Slots

​listItemView

​subtitleView

​leadingView

​titleView

​trailView

​Styling

​Style Hierarchy

​Global Level Styling

​Instance Level Styling

​Key Style Properties

​Customization Matrix

​Methods

​Swipe Action Methods

​set(options:)

​add(options:)

​Data Manipulation Methods

​insert(conversation:at:)

​getSelectedConversations()

​getConversationList()

​Connection Methods

​connect()

​disconnect()

​Text Formatter Methods

​set(textFormatters:)

​Props

​avatarStyle

​badgeStyle

​conversationRequestBuilder

​dateStyle

​dateTimeFormatter

​customSoundForMessages

​disableSoundForMessages

​disableTyping

​enablePinConversation

​hideBackButton

​hideDeleteConversationOption

​hideGroupType

​hideNavigationBar

​hidePinConversationOption

​hideReceipts

​hideSearch

​hideUserStatus

​onSearchClick

​privateGroupIcon

​protectedGroupIcon

​receiptStyle

​selectionMode

​statusIndicatorStyle

​textFormatters

​typingIndicatorStyle

​Events

​Date Time Formatter

​Global Level Formatting

​Instance Level Formatting

​Available Formatters

​Common Customizations

​Mention Configuration

​setMentionAllLabel

​Common Patterns

​Tab bar integration

Where It Fits

Minimal Render

Filtering

Filter Recipes

Actions and Events

Callback Props

onItemClick

onItemLongClick

onBack

onSelection

onError

onEmpty

onLoad

Actions Reference

Global UI Events

SDK Events (Real-Time, Automatic)

Pinning Conversations

Admin Pins

Errors

Custom View Slots

listItemView

subtitleView

leadingView

titleView

trailView

Styling

Style Hierarchy

Global Level Styling

Instance Level Styling

Key Style Properties

Customization Matrix

Methods

Swipe Action Methods

set(options:)

add(options:)

Data Manipulation Methods

insert(conversation:at:)

getSelectedConversations()

getConversationList()

Connection Methods

connect()

disconnect()

Text Formatter Methods

set(textFormatters:)

Props

avatarStyle

badgeStyle

conversationRequestBuilder

dateStyle

dateTimeFormatter

customSoundForMessages

disableSoundForMessages

disableTyping

enablePinConversation

hideBackButton

hideDeleteConversationOption

hideGroupType

hideNavigationBar

hidePinConversationOption

hideReceipts

hideSearch

hideUserStatus

onSearchClick

privateGroupIcon

protectedGroupIcon

receiptStyle

selectionMode

statusIndicatorStyle

textFormatters

typingIndicatorStyle

Events

Date Time Formatter

Global Level Formatting

Instance Level Formatting

Available Formatters

Common Customizations

Mention Configuration

setMentionAllLabel

Common Patterns

Tab bar integration