> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-ios-v5-uikit-corrections.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Components Overview

> Understand CometChat iOS UI Kit component types, base components, composite components, actions, events, filters, and customization.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "platform": "iOS UI Kit",
    "package": "CometChatUIKitSwift",
    "version": "5.1.9",
    "componentTypes": {
      "base": "Simple UI elements with no business logic",
      "components": "UI elements with built-in business logic",
      "composite": "Multiple components combined into complete features"
    },
    "baseComponents": [
      {"name": "CometChatAvatar", "purpose": "User/group profile images"},
      {"name": "CometChatBadge", "purpose": "Notification counts"},
      {"name": "CometChatStatusIndicator", "purpose": "Online/offline status"},
      {"name": "CometChatDate", "purpose": "Formatted timestamps"},
      {"name": "CometChatReceipt", "purpose": "Message delivery status"}
    ],
    "components": [
      {"name": "CometChatUsers", "purpose": "List of users"},
      {"name": "CometChatGroups", "purpose": "List of groups"},
      {"name": "CometChatConversations", "purpose": "Recent chats list"},
      {"name": "CometChatMessageList", "purpose": "Chat messages"},
      {"name": "CometChatMessageComposer", "purpose": "Message input"},
      {"name": "CometChatMessageHeader", "purpose": "Chat header"},
      {"name": "CometChatCallLogs", "purpose": "Call history"}
    ],
    "composition": {
      "note": "v5 ships NO composite/all-in-one component. The host composes the chat screen itself.",
      "chatScreen": ["CometChatMessageHeader", "CometChatMessageList", "CometChatMessageComposer"],
      "listToChat": "CometChatConversations.set(onItemClick:) -> push your own messages view controller",
      "recipe": "/ui-kit/ios/ios-conversation"
    }
  }
  ```
</Accordion>

## Overview

CometChat UI Kit provides pre-built components that you can use to quickly build a chat experience. Components are organized into three types based on complexity.

***

## Component Types

### Base Components

Simple UI elements with no business logic. They display data you pass to them.

| Component                  | Purpose                   |
| -------------------------- | ------------------------- |
| `CometChatAvatar`          | User/group profile images |
| `CometChatBadge`           | Notification counts       |
| `CometChatStatusIndicator` | Online/offline status     |
| `CometChatDate`            | Formatted timestamps      |
| `CometChatReceipt`         | Message delivery status   |

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift

    // Avatar - displays user image
    let avatar = CometChatAvatar()
    avatar.setAvatar(avatarUrl: user.avatar, with: user.name)

    // Badge - shows unread count
    let badge = CometChatBadge()
    badge.set(count: 5)

    // Status indicator - shows online status
    let status = CometChatStatusIndicator()
    status.set(status: .online)
    ```
  </Tab>
</Tabs>

***

### Components

UI elements with built-in business logic. They fetch data, handle actions, and emit events.

| Component                  | Purpose           |
| -------------------------- | ----------------- |
| `CometChatUsers`           | List of users     |
| `CometChatGroups`          | List of groups    |
| `CometChatConversations`   | Recent chats list |
| `CometChatMessageList`     | Chat messages     |
| `CometChatMessageComposer` | Message input     |
| `CometChatMessageHeader`   | Chat header       |
| `CometChatCallLogs`        | Call history      |

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift

    // Users list - fetches and displays users automatically
    let users = CometChatUsers()
    users.set(onItemClick: { user, indexPath in
        print("Selected: \(user.name ?? "")")
    })

    // Conversations - shows recent chats
    let conversations = CometChatConversations()
    conversations.set(onItemClick: { conversation, indexPath in
        // Open chat
    })

    // Message list - displays messages for a user/group
    let messageList = CometChatMessageList()
    messageList.set(user: user)
    ```
  </Tab>
</Tabs>

***

### Composing a chat screen

The UI Kit ships **no composite/all-in-one component** — you compose the chat screen yourself from
the three message components, and drive navigation from the list's `onItemClick`. This keeps your
navigation, layout, and presentation under your control.

| You want                       | Compose                                                                        |
| ------------------------------ | ------------------------------------------------------------------------------ |
| A chat screen                  | `CometChatMessageHeader` + `CometChatMessageList` + `CometChatMessageComposer` |
| Chat with user selection       | `CometChatUsers` → push your chat screen                                       |
| Chat with group selection      | `CometChatGroups` → push your chat screen                                      |
| Chat with recent conversations | `CometChatConversations` → push your chat screen                               |

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift

    // Show recent conversations, then push YOUR chat screen on selection.
    let conversations = CometChatConversations()
    conversations.set(onItemClick: { [weak self] conversation, _ in
        let messagesVC = MessagesVC()               // your view controller — see the recipe below
        messagesVC.user  = conversation.conversationWith as? User
        messagesVC.group = conversation.conversationWith as? Group
        self?.navigationController?.pushViewController(messagesVC, animated: true)
    })
    navigationController?.pushViewController(conversations, animated: true)
    ```
  </Tab>
</Tabs>

<Note>
  For the full `MessagesVC` — the three components laid out with safe-area constraints — follow
  [Conversation List + Message View](/ui-kit/ios/ios-conversation). The same pattern with a users or
  groups list is in [One-to-One / Group Chat](/ui-kit/ios/ios-one-to-one-chat), and inside a tab bar in
  [Tab-Based Chat](/ui-kit/ios/ios-tab-based-chat).
</Note>

***

## Actions

Actions define how components respond to user interactions.

### Predefined Actions

Built-in behaviors that work automatically:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // CometChatConversations has predefined actions:
    // - Tap conversation → Opens messages
    // - Long press → Shows options
    // - Swipe → Delete conversation

    let conversations = CometChatConversations()
    // These work automatically!
    ```
  </Tab>
</Tabs>

### Custom Actions

Override default behavior with your own logic:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift
    import CometChatSDK

    let conversations = CometChatConversations()

    // Override tap action
    conversations.set(onItemClick: { conversation, indexPath in
        // Your custom logic
        print("Tapped: \(conversation.conversationWith?.name ?? "")")
        
        // Navigate to custom screen instead of default
        let customChatVC = MyChatViewController()
        customChatVC.conversation = conversation
        self.navigationController?.pushViewController(customChatVC, animated: true)
    })

    // Override long press
    conversations.set(onItemLongClick: { conversation, indexPath in
        // Show custom options
        self.showCustomOptions(for: conversation)
    })

    // Handle errors
    conversations.set(onError: { error in
        print("Error: \(error.localizedDescription)")
    })

    // Handle empty state
    conversations.set(onEmpty: {
        print("No conversations")
    })
    ```
  </Tab>
</Tabs>

***

## Events

Events allow components to communicate without direct references. Subscribe to events from anywhere in your app.

### Available Events

| Event                  | Triggered When            |
| ---------------------- | ------------------------- |
| `ccMessageSent`        | Message is sent           |
| `ccMessageEdited`      | Message is edited         |
| `ccMessageDeleted`     | Message is deleted        |
| `ccMessageRead`        | Message is read           |
| `ccUserBlocked`        | User is blocked           |
| `ccUserUnblocked`      | User is unblocked         |
| `ccGroupCreated`       | Group is created          |
| `ccGroupDeleted`       | Group is deleted          |
| `ccGroupMemberAdded`   | Member added to group     |
| `ccGroupMemberRemoved` | Member removed from group |

### Subscribe to Events

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift
    import Combine

    class ChatManager {
        
        private var cancellables = Set<AnyCancellable>()
        
        func subscribeToEvents() {
            // Message sent event
            CometChatMessageEvents.ccMessageSent
                .sink { message in
                    print("Message sent: \(message.text ?? "")")
                    // Update UI, analytics, etc.
                }
                .store(in: &cancellables)
            
            // Message deleted event
            CometChatMessageEvents.ccMessageDeleted
                .sink { message in
                    print("Message deleted: \(message.id)")
                }
                .store(in: &cancellables)
            
            // User blocked event
            CometChatUserEvents.ccUserBlocked
                .sink { user in
                    print("Blocked: \(user.name ?? "")")
                }
                .store(in: &cancellables)
            
            // Group member added
            CometChatGroupEvents.ccGroupMemberAdded
                .sink { (action, addedBy, addedUser, group) in
                    print("\(addedUser.name ?? "") added to \(group.name ?? "")")
                }
                .store(in: &cancellables)
        }
        
        func unsubscribe() {
            cancellables.removeAll()
        }
    }
    ```
  </Tab>
</Tabs>

***

## Configuring components

Because you compose the chat screen yourself, you configure **each component directly on its own
instance** — there is no configuration object to pass down through a parent.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift

    // Header — set the target, then customize it directly
    let messageHeader = CometChatMessageHeader()
    messageHeader.set(user: user)
    messageHeader.set(controller: self)
    messageHeader.hideBackButton = false
    messageHeader.set(subtitleView: { user, group in
        let label = UILabel()
        label.font = UIFont.systemFont(ofSize: 13)
        label.textColor = .secondaryLabel
        label.text = user?.status == .online ? "Online" : "Offline"
        return label
    })

    // Message list — same target, its own empty/error views
    let messageList = CometChatMessageList()
    messageList.set(user: user)
    messageList.set(controller: self)
    messageList.set(emptyView: myEmptyView)
    messageList.set(errorView: myErrorView)

    // Composer — same target
    let composer = CometChatMessageComposer()
    composer.set(user: user)
    composer.set(controller: self)
    composer.placeholderText = "Type a message..."
    ```
  </Tab>
</Tabs>

<Note>
  Pass the **same** `user` (or `group`) to all three components — that shared target is what keeps the
  header, list, and composer on the same conversation. Component-specific configuration objects do exist
  for nested sub-features (for example `ReactionsConfiguration`, `StickerKeyboardConfiguration`,
  `IncomingCallConfiguration`); see each component's own page for its full API.
</Note>

***

## Component Hierarchy

```
YourNavigationController              // yours
├── CometChatConversations            // list screen
│   └── CometChatListItem
│       ├── CometChatAvatar
│       ├── CometChatBadge
│       ├── CometChatStatusIndicator
│       └── CometChatDate
└── MessagesVC                        // YOUR view controller, pushed on selection
    ├── CometChatMessageHeader
    │   ├── CometChatAvatar
    │   └── CometChatStatusIndicator
    ├── CometChatMessageList
    │   ├── CometChatMessageBubble
    │   ├── CometChatReceipt
    │   └── CometChatDate
    └── CometChatMessageComposer
        ├── CometChatMediaRecorder
        └── CometChatStickerKeyboard
```

The two levels you own are the navigation controller and `MessagesVC`; everything below them is a
UI Kit component.

***

## Quick Reference

### When to Use Each Type

| Need                                    | Use                                                                                       |
| --------------------------------------- | ----------------------------------------------------------------------------------------- |
| Display user avatar                     | `CometChatAvatar` (Base)                                                                  |
| Show list of users                      | `CometChatUsers` (Component)                                                              |
| Complete chat with user selection       | `CometChatUsers` → push your chat screen ([recipe](/ui-kit/ios/ios-one-to-one-chat))      |
| Complete chat with recent conversations | `CometChatConversations` → push your chat screen ([recipe](/ui-kit/ios/ios-conversation)) |
| Custom chat UI                          | Individual Components                                                                     |

### Common Patterns

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // Pattern 1: Recent conversations -> your chat screen
    let conversations = CometChatConversations()
    conversations.set(onItemClick: { [weak self] conversation, _ in
        let messagesVC = MessagesVC()
        messagesVC.user  = conversation.conversationWith as? User
        messagesVC.group = conversation.conversationWith as? Group
        self?.navigationController?.pushViewController(messagesVC, animated: true)
    })

    // Pattern 2: User list -> your chat screen
    let users = CometChatUsers()
    users.set(onItemClick: { [weak self] user, _ in
        let messagesVC = MessagesVC()
        messagesVC.user = user
        self?.navigationController?.pushViewController(messagesVC, animated: true)
    })

    // Pattern 3: Fully custom with base components
    let customCell = UITableViewCell()
    let avatar = CometChatAvatar()
    avatar.setAvatar(avatarUrl: user.avatar, with: user.name)
    customCell.contentView.addSubview(avatar)
    ```
  </Tab>
</Tabs>

***

## Related

* [Component Styling](/ui-kit/ios/component-styling) - Customize appearance
* [Color Resources](/ui-kit/ios/color-resources) - Theme colors
* [Getting Started](/ui-kit/ios/getting-started) - Initial setup