Components Overview

Understanding CometChat iOS UI Kit components - types, actions, events, and customization

AI Agent Platform Spec

{
  "platform": "iOS UI Kit",
  "package": "CometChatUIKitSwift",
  "version": "5.0.0",
  "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"]}
  ]
}

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)

---

Composite Components

Combine multiple components into complete features.

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

Swift

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)

---

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

---

Configurations

Customize nested components within composite components:

Swift

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)

---

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

Swift

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

---

Related

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