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

# Conversations

> Display CometChat iOS UI Kit conversations with last messages, unread counts, typing indicators, presence, filters, and item callbacks.

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.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/jpEUuHUk-hvu4tQT/images/a64b9191-Conversation-b61978dd3caa80a24c801de3492fe2b5.png?fit=max&auto=format&n=jpEUuHUk-hvu4tQT&q=85&s=4d7d6bc6e54df72e32696f5bb7c3ef35" alt="CometChatConversations showing a list of recent conversations with user avatars, last message previews, timestamps, and unread message badges" width="1280" height="800" data-path="images/a64b9191-Conversation-b61978dd3caa80a24c801de3492fe2b5.png" />
</Frame>

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "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",
        "tailView": "(Conversation) -> UIView",
        "emptyStateView": "() -> UIView",
        "errorStateView": "() -> UIView",
        "loadingStateView": "() -> UIView"
      },
      "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", "CometChatMessages"],
      "flow": "User taps conversation → onItemClick fires → Navigate to CometChatMessages with user/group"
    },
    "types": {
      "Conversation": {
        "conversationId": "String?",
        "conversationType": "ConversationType",
        "conversationWith": "AppEntity?",
        "lastMessage": "BaseMessage?",
        "unreadMessageCount": "Int"
      },
      "ConversationType": {
        "user": "One-on-one conversation",
        "group": "Group conversation",
        "both": "All conversation types"
      }
    }
  }
  ```
</Accordion>

| 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 and navigates to `CometChatMessages` when a conversation is selected.

```swift lines theme={null}
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 = CometChatMessages()
        
        if let user = conversation.conversationWith as? User {
            messagesVC.set(user: user)
        } else if let group = conversation.conversationWith as? Group {
            messagesVC.set(group: group)
        }
        
        navigationController?.pushViewController(messagesVC, animated: true)
    }
}
```

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/jpEUuHUk-hvu4tQT/images/a64b9191-Conversation-b61978dd3caa80a24c801de3492fe2b5.png?fit=max&auto=format&n=jpEUuHUk-hvu4tQT&q=85&s=4d7d6bc6e54df72e32696f5bb7c3ef35" alt="CometChatConversations showing integration flow with conversation list navigating to messages screen" width="1280" height="800" data-path="images/a64b9191-Conversation-b61978dd3caa80a24c801de3492fe2b5.png" />
</Frame>

***

## Minimal Render

```swift lines theme={null}
import CometChatUIKitSwift

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

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/jpEUuHUk-hvu4tQT/images/a64b9191-Conversation-b61978dd3caa80a24c801de3492fe2b5.png?fit=max&auto=format&n=jpEUuHUk-hvu4tQT&q=85&s=4d7d6bc6e54df72e32696f5bb7c3ef35" alt="CometChatConversations showing minimal render with default configuration displaying conversation list" width="1280" height="800" data-path="images/a64b9191-Conversation-b61978dd3caa80a24c801de3492fe2b5.png" />
</Frame>

***

## Filtering

Use `ConversationRequest.ConversationRequestBuilder` to filter which conversations 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 requestBuilder = ConversationRequest.ConversationRequestBuilder(limit: 30)
    .set(conversationType: .both)

let conversations = CometChatConversations(conversationRequestBuilder: requestBuilder)
```

### Filter Recipes

| Recipe                     | Code                                              |
| -------------------------- | ------------------------------------------------- |
| Show only one-on-one chats | `.set(conversationType: .user)`                   |
| Show only group chats      | `.set(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.

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let conversations = CometChatConversations()

conversations.set(onItemClick: { [weak self] conversation, indexPath in
    guard let self = self else { return }
    
    let messagesVC = CometChatMessages()
    
    if let user = conversation.conversationWith as? User {
        messagesVC.set(user: user)
    } else if let group = conversation.conversationWith as? Group {
        messagesVC.set(group: 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.

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

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

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

```swift lines theme={null}
import CometChatUIKitSwift

let conversations = CometChatConversations()

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

#### onEmpty

Fires when the conversation list is empty.

```swift lines theme={null}
import CometChatUIKitSwift

let conversations = CometChatConversations()

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

#### onLoad

Fires when conversations are successfully loaded.

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

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

***

## 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     |
| `tailView`         | `(Conversation) -> UIView` | Right side (time, badge) |
| `emptyStateView`   | `() -> UIView`             | Empty state display      |
| `errorStateView`   | `() -> UIView`             | Error state display      |
| `loadingStateView` | `() -> UIView`             | Loading state display    |

### listItemView

Replace the entire conversation row with a custom design.

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

let conversations = CometChatConversations()

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

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

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

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

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

### tailView

Customize the right side of the conversation row (time, unread badge). Note: The setter method is `set(trailView:)`.

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

1. Global styles (`CometChatConversation.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 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

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

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/jpEUuHUk-hvu4tQT/images/a64b9191-Conversation-b61978dd3caa80a24c801de3492fe2b5.png?fit=max&auto=format&n=jpEUuHUk-hvu4tQT&q=85&s=4d7d6bc6e54df72e32696f5bb7c3ef35" alt="CometChatConversations with custom styling applied showing customized background, colors, and list item appearance" width="1280" height="800" data-path="images/a64b9191-Conversation-b61978dd3caa80a24c801de3492fe2b5.png" />
</Frame>

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

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

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

```swift lines theme={null}
@discardableResult
public func add(options: ((_ conversation: Conversation?) -> [CometChatConversationOption])?) -> Self
```

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

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

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

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

```swift lines theme={null}
public func getSelectedConversations() -> [Conversation]
```

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

```swift lines theme={null}
public func getConversationList() -> [Conversation]
```

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

```swift lines theme={null}
public func connect()
```

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

```swift lines theme={null}
public func disconnect()
```

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

```swift lines theme={null}
@discardableResult
public func set(textFormatters: [CometChatTextFormatter]) -> Self
```

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

```swift lines theme={null}
import CometChatUIKitSwift

let conversations = CometChatConversations()

// Create custom text formatters
let mentionFormatter = CometChatMentionTextFormatter()
let urlFormatter = CometChatURLTextFormatter()

conversations.set(textFormatters: [mentionFormatter, urlFormatter])
```

***

## Props

All props are optional. Sorted alphabetically.

### avatarStyle

Customizes the appearance of avatars in conversation list items.

|         |                 |
| ------- | --------------- |
| Type    | `AvatarStyle`   |
| Default | `AvatarStyle()` |

```swift lines theme={null}
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.set(avatarStyle: avatarStyle)
```

### badgeStyle

Customizes the appearance of unread message count badges.

|         |                |
| ------- | -------------- |
| Type    | `BadgeStyle`   |
| Default | `BadgeStyle()` |

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

```swift lines theme={null}
import CometChatUIKitSwift

let conversations = CometChatConversations()

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

conversations.set(dateStyle: dateStyle)
```

### dateTimeFormatter

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

|         |                               |
| ------- | ----------------------------- |
| Type    | `CometChatDateTimeFormatter?` |
| Default | `nil`                         |

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

```swift lines theme={null}
import CometChatUIKitSwift

let conversations = CometChatConversations()
conversations.disableTyping = 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` |

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

```swift lines theme={null}
import CometChatUIKitSwift

let conversations = CometChatConversations()

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

### privateGroupIcon

Custom icon for private group conversations.

|         |            |
| ------- | ---------- |
| Type    | `UIImage?` |
| Default | `nil`      |

```swift lines theme={null}
import CometChatUIKitSwift

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

### protectedGroupIcon

Custom icon for password-protected group conversations.

|         |            |
| ------- | ---------- |
| Type    | `UIImage?` |
| Default | `nil`      |

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

```swift lines theme={null}
import CometChatUIKitSwift

let conversations = CometChatConversations()

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

conversations.set(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()` |

```swift lines theme={null}
import CometChatUIKitSwift

let conversations = CometChatConversations()

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

conversations.set(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()` |

```swift lines theme={null}
import CometChatUIKitSwift

let conversations = CometChatConversations()

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

conversations.set(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

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

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

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

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

```swift lines theme={null}
import CometChatUIKitSwift

let conversations = CometChatConversations()

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

```swift lines theme={null}
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 = CometChatMessages()
        
        if let user = conversation.conversationWith as? User {
            messagesVC.set(user: user)
        } else if let group = conversation.conversationWith as? Group {
            messagesVC.set(group: group)
        }
        
        navigationController?.pushViewController(messagesVC, animated: true)
    }
}
```

***

## Common Patterns

### Tab bar integration

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

```swift lines theme={null}
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 = CometChatMessages()
            
            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

```swift lines theme={null}
let conversations = CometChatConversations()

conversations.set(emptyStateView: {
    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...
    return emptyView
})
```

### Hide all chrome — minimal list

```swift lines theme={null}
let conversations = CometChatConversations()
conversations.hideReceipts = true
conversations.hideUserStatus = true
conversations.hideGroupType = true
conversations.hideDeleteConversationOption = true
```

### Filter by conversation type

```swift lines theme={null}
// Only user conversations
let userOnlyBuilder = ConversationRequest.ConversationRequestBuilder(limit: 30)
    .set(conversationType: .user)

let conversations = CometChatConversations(conversationRequestBuilder: userOnlyBuilder)

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

let groupConversations = CometChatConversations(conversationRequestBuilder: groupOnlyBuilder)
```

***

## Related Components

* [Messages](/ui-kit/ios/message-list) - Display messages in a conversation
* [Users](/ui-kit/ios/users) - List all users to start new conversations
* [Groups](/ui-kit/ios/groups) - List all groups
* [Message Composer](/ui-kit/ios/message-composer) - Send messages in a conversation
* [Conversation With Messages](/ui-kit/ios/conversations) - Combined conversations and messages view