Components Overview

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

AI Integration Quick Reference

{
  "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"
  }
}

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

Swift

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)

---

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

Swift

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)

---

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

Swift

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)

For the full MessagesVC — the three components laid out with safe-area constraints — follow Conversation List + Message View. The same pattern with a users or groups list is in One-to-One / Group Chat, and inside a tab bar in Tab-Based Chat.

---

Actions

Actions define how components respond to user interactions.

Predefined Actions

Built-in behaviors that work automatically:

Swift

// CometChatConversations has predefined actions:
// - Tap conversation → Opens messages
// - Long press → Shows options
// - Swipe → Delete conversation

let conversations = CometChatConversations()
// These work automatically!

Custom Actions

Override default behavior with your own logic:

Swift

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")
})

---

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

Swift

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()
    }
}

---

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.

Swift

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

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.

---

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)
Complete chat with recent conversations	CometChatConversations → push your chat screen (recipe)
Custom chat UI	Individual Components

Common Patterns

Swift

// 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)

---

Related

• Component Styling - Customize appearance
• Color Resources - Theme colors
• Getting Started - Initial setup