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

# 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"}
    ],
    "compositeComponents": [
      {"name": "CometChatMessages", "contains": ["MessageHeader", "MessageList", "MessageComposer"]},
      {"name": "CometChatUsersWithMessages", "contains": ["Users", "Messages"]},
      {"name": "CometChatGroupsWithMessages", "contains": ["Groups", "Messages"]},
      {"name": "CometChatConversationsWithMessages", "contains": ["Conversations", "Messages"]}
    ]
  }
  ```
</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>

***

### Composite Components

Combine multiple components into complete features.

| Component                            | Contains                                      |
| ------------------------------------ | --------------------------------------------- |
| `CometChatMessages`                  | MessageHeader + MessageList + MessageComposer |
| `CometChatUsersWithMessages`         | Users + Messages                              |
| `CometChatGroupsWithMessages`        | Groups + Messages                             |
| `CometChatConversationsWithMessages` | Conversations + Messages                      |

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

    // Complete chat experience in one component
    let conversationsWithMessages = CometChatConversationsWithMessages()
    navigationController?.pushViewController(conversationsWithMessages, animated: true)

    // Or just the messages view
    let messages = CometChatMessages()
    messages.user = user  // or messages.group = group
    navigationController?.pushViewController(messages, animated: true)
    ```
  </Tab>
</Tabs>

***

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

***

## Configurations

Customize nested components within composite components:

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

    // CometChatMessages contains: MessageHeader, MessageList, MessageComposer
    // You can configure each one:

    let messages = CometChatMessages()
    messages.user = user

    // Configure MessageHeader
    let headerConfig = MessageHeaderConfiguration()
    headerConfig.hideBackButton = false
    headerConfig.set(subtitleView: { user, group in
        let label = UILabel()
        label.text = user?.status == .online ? "Online" : "Offline"
        label.textColor = user?.status == .online ? .systemGreen : .gray
        return label
    })
    messages.set(messageHeaderConfiguration: headerConfig)

    // Configure MessageList
    let listConfig = MessageListConfiguration()
    listConfig.set(emptyStateText: "No messages yet")
    listConfig.set(errorStateText: "Failed to load messages")
    messages.set(messageListConfiguration: listConfig)

    // Configure MessageComposer
    let composerConfig = MessageComposerConfiguration()
    composerConfig.set(placeholderText: "Type a message...")
    composerConfig.hideLiveReaction = true
    messages.set(messageComposerConfiguration: composerConfig)
    ```
  </Tab>
</Tabs>

***

## Component Hierarchy

```
CometChatConversationsWithMessages
├── CometChatConversations
│   ├── CometChatListItem
│   │   ├── CometChatAvatar
│   │   ├── CometChatBadge
│   │   ├── CometChatStatusIndicator
│   │   └── CometChatDate
│   └── CometChatListBase
└── CometChatMessages
    ├── CometChatMessageHeader
    │   ├── CometChatAvatar
    │   └── CometChatStatusIndicator
    ├── CometChatMessageList
    │   ├── CometChatMessageBubble
    │   ├── CometChatReceipt
    │   └── CometChatDate
    └── CometChatMessageComposer
        ├── CometChatMediaRecorder
        └── CometChatStickerKeyboard
```

***

## 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 | `CometChatUsersWithMessages` (Composite) |
| Custom chat UI                    | Individual Components                    |
| Quick integration                 | Composite Components                     |

### Common Patterns

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // Pattern 1: Quick integration with composite
    let chat = CometChatConversationsWithMessages()
    navigationController?.pushViewController(chat, animated: true)

    // Pattern 2: Custom flow with components
    let users = CometChatUsers()
    users.set(onItemClick: { user, _ in
        let messages = CometChatMessages()
        messages.user = user
        self.navigationController?.pushViewController(messages, 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