cometchat-ios-placement— agent skill

Ground truth: CometChatUIKitSwift ~> 5 view controllers + docs/ui-kit/ios. Official docs: https://www.cometchat.com/docs/ui-kit/ios/overview · Docs MCP: claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp (or fetch the URL directly without MCP). Verify symbols against the installed package/source before relying on them.

Purpose

This skill teaches WHERE to place CometChat components in your iOS app. It covers navigation patterns, tab bar integration, modal presentations, and embedded views for different use cases.

1. Navigation Stack Pattern

The most common pattern for messaging apps. Push conversations onto a navigation stack.

Basic Navigation Flow

┌─────────────────────────────────────────────────────────────┐
│  UINavigationController                                      │
│  ┌─────────────────────────────────────────────────────────┐│
│  │  CometChatConversations                                 ││
│  │  ┌─────────────────────────────────────────────────────┐││
│  │  │  Conversation 1                                     │││
│  │  │  Conversation 2  ──────────────────────────────────►│││
│  │  │  Conversation 3                                     │││
│  │  └─────────────────────────────────────────────────────┘││
│  └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  MessagesViewController (pushed)                             │
│  ┌─────────────────────────────────────────────────────────┐│
│  │  CometChatMessageHeader                                 ││
│  ├─────────────────────────────────────────────────────────┤│
│  │  CometChatMessageList                                   ││
│  │                                                         ││
│  │                                                         ││
│  ├─────────────────────────────────────────────────────────┤│
│  │  CometChatMessageComposer                               ││
│  └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘

Implementation (UIKit)

// SceneDelegate.swift
func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
    guard let windowScene = (scene as? UIWindowScene) else { return }
    
    let window = UIWindow(windowScene: windowScene)
    
    // Create conversations list
    let conversations = CometChatConversations()
    conversations.set(onItemClick: { [weak conversations] conversation, _ in
        let messagesVC = MessagesVC()  // your own VC composing CometChatMessageHeader + List + Composer; see cometchat-ios-components § 12
        if let user = conversation.conversationWith as? User {
            messagesVC.user = user
        } else if let group = conversation.conversationWith as? Group {
            messagesVC.group = group
        }
        conversations?.navigationController?.pushViewController(messagesVC, animated: true)
    })
    
    // Wrap in navigation controller
    let navController = UINavigationController(rootViewController: conversations)
    
    window.rootViewController = navController
    self.window = window
    window.makeKeyAndVisible()
}

Implementation (SwiftUI)

import SwiftUI
import CometChatUIKitSwift
import CometChatSDK

struct ChatNavigationView: View {
    @State private var selectedConversation: Conversation?
    @State private var showMessages = false
    
    var body: some View {
        NavigationStack {
            ConversationsListView(selectedConversation: $selectedConversation)
                .navigationDestination(isPresented: $showMessages) {
                    if let conversation = selectedConversation {
                        MessagesView(conversation: conversation)
                    }
                }
                .onChange(of: selectedConversation) { newValue in
                    showMessages = newValue != nil
                }
        }
    }
}

struct ConversationsListView: UIViewControllerRepresentable {
    @Binding var selectedConversation: Conversation?
    
    func makeUIViewController(context: Context) -> CometChatConversations {
        let conversations = CometChatConversations()
        conversations.set(onItemClick: { conversation, _ in
            selectedConversation = conversation
        })
        return conversations
    }
    
    func updateUIViewController(_ uiViewController: CometChatConversations, context: Context) {}
}

2. Tab Bar Pattern

For apps where chat is one of several main features.

Tab Layout

┌─────────────────────────────────────────────────────────────┐
│                                                             │
│                    Content Area                             │
│                                                             │
│                                                             │
│                                                             │
├─────────────────────────────────────────────────────────────┤
│  ┌─────┐  ┌─────┐  ┌─────┐  ┌─────┐  ┌─────┐              │
│  │Home │  │Chats│  │Users│  │Groups│ │Calls│              │
│  └─────┘  └─────┘  └─────┘  └─────┘  └─────┘              │
└─────────────────────────────────────────────────────────────┘

Implementation (UIKit)

import UIKit
import CometChatUIKitSwift
import CometChatSDK

class MainTabBarController: UITabBarController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        setupTabs()
    }
    
    private func setupTabs() {
        // Home tab (your existing content)
        let homeVC = HomeViewController()
        homeVC.tabBarItem = UITabBarItem(
            title: "Home",
            image: UIImage(systemName: "house"),
            selectedImage: UIImage(systemName: "house.fill")
        )
        
        // Chats tab
        let chatsVC = createChatsTab()
        let chatsNav = UINavigationController(rootViewController: chatsVC)
        chatsNav.tabBarItem = UITabBarItem(
            title: "Chats",
            image: UIImage(systemName: "message"),
            selectedImage: UIImage(systemName: "message.fill")
        )
        
        // Users tab
        let usersVC = CometChatUsers()
        usersVC.set(onItemClick: { [weak self] user, _ in
            self?.openMessages(with: user)
        })
        let usersNav = UINavigationController(rootViewController: usersVC)
        usersNav.tabBarItem = UITabBarItem(
            title: "Users",
            image: UIImage(systemName: "person.2"),
            selectedImage: UIImage(systemName: "person.2.fill")
        )
        
        // Groups tab
        let groupsVC = CometChatGroups()
        groupsVC.set(onItemClick: { [weak self] group, _ in
            self?.openMessages(with: group)
        })
        let groupsNav = UINavigationController(rootViewController: groupsVC)
        groupsNav.tabBarItem = UITabBarItem(
            title: "Groups",
            image: UIImage(systemName: "person.3"),
            selectedImage: UIImage(systemName: "person.3.fill")
        )
        
        var tabs: [UIViewController] = [
            UINavigationController(rootViewController: homeVC),
            chatsNav,
            usersNav,
            groupsNav
        ]
        
        // Calls tab - only available if CometChatCallsSDK is installed
        #if canImport(CometChatCallsSDK)
        let callsVC = CometChatCallLogs()
        let callsNav = UINavigationController(rootViewController: callsVC)
        callsNav.tabBarItem = UITabBarItem(
            title: "Calls",
            image: UIImage(systemName: "phone"),
            selectedImage: UIImage(systemName: "phone.fill")
        )
        tabs.append(callsNav)
        #endif
        
        viewControllers = tabs
    }
    
    private func createChatsTab() -> CometChatConversations {
        let conversations = CometChatConversations()
        conversations.set(onItemClick: { [weak self] conversation, _ in
            if let user = conversation.conversationWith as? User {
                self?.openMessages(with: user)
            } else if let group = conversation.conversationWith as? Group {
                self?.openMessages(with: group)
            }
        })
        return conversations
    }
    
    private func openMessages(with user: User) {
        let messagesVC = MessagesVC()  // your own VC composing CometChatMessageHeader + List + Composer; see cometchat-ios-components § 12
        messagesVC.user = user
        messagesVC.hidesBottomBarWhenPushed = true
        
        if let navController = selectedViewController as? UINavigationController {
            navController.pushViewController(messagesVC, animated: true)
        }
    }
    
    private func openMessages(with group: Group) {
        let messagesVC = MessagesVC()  // your own VC composing CometChatMessageHeader + List + Composer; see cometchat-ios-components § 12
        messagesVC.group = group
        messagesVC.hidesBottomBarWhenPushed = true
        
        if let navController = selectedViewController as? UINavigationController {
            navController.pushViewController(messagesVC, animated: true)
        }
    }
}

Implementation (SwiftUI)

struct MainTabView: View {
    @State private var selectedTab = 0
    
    var body: some View {
        TabView(selection: $selectedTab) {
            HomeView()
                .tabItem {
                    Label("Home", systemImage: "house")
                }
                .tag(0)
            
            ChatNavigationView()
                .tabItem {
                    Label("Chats", systemImage: "message")
                }
                .tag(1)
            
            UsersNavigationView()
                .tabItem {
                    Label("Users", systemImage: "person.2")
                }
                .tag(2)
            
            GroupsNavigationView()
                .tabItem {
                    Label("Groups", systemImage: "person.3")
                }
                .tag(3)
            
            CallsNavigationView()
                .tabItem {
                    Label("Calls", systemImage: "phone")
                }
                .tag(4)
        }
    }
}

3. Modal Presentation Pattern

For apps where chat is a secondary feature, presented modally.

Modal Layout

┌─────────────────────────────────────────────────────────────┐
│  Your App Content                                           │
│                                                             │
│  ┌─────────────────────────────────────────────────────────┐│
│  │  Product Details                                        ││
│  │                                                         ││
│  │  ┌─────────────────────────────────────────────────────┐││
│  │  │  [Chat with Seller]  ◄─────────────────────────────│││
│  │  └─────────────────────────────────────────────────────┘││
│  └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼ (modal presentation)
┌─────────────────────────────────────────────────────────────┐
│  ┌─────────────────────────────────────────────────────────┐│
│  │  [X]  Chat with John                                    ││
│  ├─────────────────────────────────────────────────────────┤│
│  │                                                         ││
│  │  Messages                                               ││
│  │                                                         ││
│  ├─────────────────────────────────────────────────────────┤│
│  │  Composer                                               ││
│  └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘

Implementation (UIKit)

class ProductDetailViewController: UIViewController {
    
    var sellerUID: String?
    
    @IBAction func chatWithSellerTapped(_ sender: UIButton) {
        guard let sellerUID = sellerUID else { return }
        
        // Fetch the seller user
        CometChat.getUser(UID: sellerUID) { [weak self] user in
            guard let user = user else { return }
            
            DispatchQueue.main.async {
                let messagesVC = MessagesVC()  // your own VC composing CometChatMessageHeader + List + Composer; see cometchat-ios-components § 12
                messagesVC.user = user
                
                let navController = UINavigationController(rootViewController: messagesVC)
                navController.modalPresentationStyle = .pageSheet
                
                // Add close button
                messagesVC.navigationItem.leftBarButtonItem = UIBarButtonItem(
                    barButtonSystemItem: .close,
                    target: self,
                    action: #selector(self?.dismissChat)
                )
                
                self?.present(navController, animated: true)
            }
        } onError: { error in
            print("Error fetching user: \(error?.errorDescription ?? "")")
        }
    }
    
    @objc private func dismissChat() {
        dismiss(animated: true)
    }
}

Implementation (SwiftUI)

struct ProductDetailView: View {
    let sellerUID: String
    @State private var showChat = false
    @State private var seller: User?
    
    var body: some View {
        VStack {
            // Product details...
            
            Button("Chat with Seller") {
                fetchSellerAndShowChat()
            }
            .buttonStyle(.borderedProminent)
        }
        .sheet(isPresented: $showChat) {
            if let seller = seller {
                NavigationStack {
                    MessagesView(user: seller)
                        .toolbar {
                            ToolbarItem(placement: .navigationBarLeading) {
                                Button("Close") {
                                    showChat = false
                                }
                            }
                        }
                }
            }
        }
    }
    
    private func fetchSellerAndShowChat() {
        CometChat.getUser(UID: sellerUID) { user in
            DispatchQueue.main.async {
                self.seller = user
                self.showChat = true
            }
        } onError: { error in
            print("Error: \(error?.errorDescription ?? "")")
        }
    }
}

4. Floating Button Pattern

For support chat or quick access to messages.

Floating Button Layout

┌─────────────────────────────────────────────────────────────┐
│  Your App Content                                           │
│                                                             │
│                                                             │
│                                                             │
│                                                             │
│                                                             │
│                                                             │
│                                                     ┌─────┐ │
│                                                     │ 💬  │ │
│                                                     └─────┘ │
└─────────────────────────────────────────────────────────────┘

Implementation (UIKit)

class FloatingChatButton: UIButton {
    
    private var unreadCount: Int = 0 {
        didSet {
            updateBadge()
        }
    }
    
    private lazy var badgeLabel: UILabel = {
        let label = UILabel()
        label.backgroundColor = .systemRed
        label.textColor = .white
        label.font = .systemFont(ofSize: 12, weight: .bold)
        label.textAlignment = .center
        label.layer.cornerRadius = 10
        label.clipsToBounds = true
        label.isHidden = true
        return label
    }()
    
    override init(frame: CGRect) {
        super.init(frame: frame)
        setupButton()
    }
    
    required init?(coder: NSCoder) {
        super.init(coder: coder)
        setupButton()
    }
    
    private func setupButton() {
        backgroundColor = .systemBlue
        layer.cornerRadius = 28
        layer.shadowColor = UIColor.black.cgColor
        layer.shadowOffset = CGSize(width: 0, height: 4)
        layer.shadowRadius = 8
        layer.shadowOpacity = 0.3
        
        setImage(UIImage(systemName: "message.fill"), for: .normal)
        tintColor = .white
        
        addSubview(badgeLabel)
        badgeLabel.translatesAutoresizingMaskIntoConstraints = false
        NSLayoutConstraint.activate([
            badgeLabel.topAnchor.constraint(equalTo: topAnchor, constant: -5),
            badgeLabel.trailingAnchor.constraint(equalTo: trailingAnchor, constant: 5),
            badgeLabel.widthAnchor.constraint(greaterThanOrEqualToConstant: 20),
            badgeLabel.heightAnchor.constraint(equalToConstant: 20)
        ])
    }
    
    private func updateBadge() {
        badgeLabel.isHidden = unreadCount == 0
        badgeLabel.text = unreadCount > 99 ? "99+" : "\(unreadCount)"
    }
    
    func setUnreadCount(_ count: Int) {
        unreadCount = count
    }
}

// Usage in a view controller
class MainViewController: UIViewController {
    
    private lazy var chatButton: FloatingChatButton = {
        let button = FloatingChatButton()
        button.addTarget(self, action: #selector(openChat), for: .touchUpInside)
        return button
    }()
    
    override func viewDidLoad() {
        super.viewDidLoad()
        setupFloatingButton()
    }
    
    private func setupFloatingButton() {
        view.addSubview(chatButton)
        chatButton.translatesAutoresizingMaskIntoConstraints = false
        NSLayoutConstraint.activate([
            chatButton.trailingAnchor.constraint(equalTo: view.safeAreaLayoutGuide.trailingAnchor, constant: -20),
            chatButton.bottomAnchor.constraint(equalTo: view.safeAreaLayoutGuide.bottomAnchor, constant: -20),
            chatButton.widthAnchor.constraint(equalToConstant: 56),
            chatButton.heightAnchor.constraint(equalToConstant: 56)
        ])
    }
    
    @objc private func openChat() {
        let conversations = CometChatConversations()
        conversations.set(onItemClick: { [weak self] conversation, _ in
            let messagesVC = MessagesVC()  // your own VC composing CometChatMessageHeader + List + Composer; see cometchat-ios-components § 12
            if let user = conversation.conversationWith as? User {
                messagesVC.user = user
            } else if let group = conversation.conversationWith as? Group {
                messagesVC.group = group
            }
            conversations.navigationController?.pushViewController(messagesVC, animated: true)
        })
        
        let navController = UINavigationController(rootViewController: conversations)
        navController.modalPresentationStyle = .pageSheet
        
        conversations.navigationItem.leftBarButtonItem = UIBarButtonItem(
            barButtonSystemItem: .close,
            target: self,
            action: #selector(dismissChat)
        )
        
        present(navController, animated: true)
    }
    
    @objc private func dismissChat() {
        dismiss(animated: true)
    }
}

5. Split View Pattern (iPad)

For iPad apps with master-detail layout.

Split View Layout

┌─────────────────────────────────────────────────────────────────────────────┐
│  ┌─────────────────────────┐  ┌─────────────────────────────────────────────┐│
│  │  Conversations          │  │  Messages                                   ││
│  │  ┌─────────────────────┐│  │  ┌─────────────────────────────────────────┐││
│  │  │  John Doe           ││  │  │  Header                                 │││
│  │  │  Jane Smith  ◄──────┼┼──┼──┤─────────────────────────────────────────│││
│  │  │  Team Chat          ││  │  │  Message List                           │││
│  │  │                     ││  │  │                                         │││
│  │  │                     ││  │  │                                         │││
│  │  │                     ││  │  ├─────────────────────────────────────────┤││
│  │  │                     ││  │  │  Composer                               │││
│  │  └─────────────────────┘│  │  └─────────────────────────────────────────┘││
│  └─────────────────────────┘  └─────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────────────────┘

Implementation (UIKit)

class ChatSplitViewController: UISplitViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        preferredDisplayMode = .oneBesideSecondary
        preferredSplitBehavior = .tile
        
        // Primary: Conversations
        let conversations = CometChatConversations()
        conversations.set(onItemClick: { [weak self] conversation, _ in
            self?.showMessages(for: conversation)
        })
        let primaryNav = UINavigationController(rootViewController: conversations)
        
        // Secondary: Empty state or messages
        let emptyVC = EmptyStateViewController()
        let secondaryNav = UINavigationController(rootViewController: emptyVC)
        
        viewControllers = [primaryNav, secondaryNav]
    }
    
    private func showMessages(for conversation: Conversation) {
        let messagesVC = MessagesVC()  // your own VC composing CometChatMessageHeader + List + Composer; see cometchat-ios-components § 12
        
        if let user = conversation.conversationWith as? User {
            messagesVC.user = user
        } else if let group = conversation.conversationWith as? Group {
            messagesVC.group = group
        }
        
        let secondaryNav = UINavigationController(rootViewController: messagesVC)
        showDetailViewController(secondaryNav, sender: self)
    }
}

class EmptyStateViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad()
        view.backgroundColor = .systemBackground
        
        let label = UILabel()
        label.text = "Select a conversation"
        label.textColor = .secondaryLabel
        label.textAlignment = .center
        
        view.addSubview(label)
        label.translatesAutoresizingMaskIntoConstraints = false
        NSLayoutConstraint.activate([
            label.centerXAnchor.constraint(equalTo: view.centerXAnchor),
            label.centerYAnchor.constraint(equalTo: view.centerYAnchor)
        ])
    }
}

6. Embedded View Pattern

For embedding chat in a portion of the screen.

Embedded Layout

┌─────────────────────────────────────────────────────────────┐
│  Your App Header                                            │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────────┐│
│  │  Your Content                                           ││
│  │                                                         ││
│  └─────────────────────────────────────────────────────────┘│
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────────┐│
│  │  Embedded Chat (CometChatMessageList + Composer)        ││
│  │                                                         ││
│  └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘

Implementation (UIKit)

class EmbeddedChatViewController: UIViewController {
    
    private var supportUser: User?
    
    private lazy var chatContainer: UIView = {
        let view = UIView()
        view.backgroundColor = .systemBackground
        view.layer.cornerRadius = 12
        view.clipsToBounds = true
        return view
    }()
    
    private lazy var messageList = CometChatMessageList()
    private lazy var messageComposer = CometChatMessageComposer()
    
    override func viewDidLoad() {
        super.viewDidLoad()
        setupUI()
        fetchSupportUser()
    }
    
    private func setupUI() {
        view.addSubview(chatContainer)
        chatContainer.translatesAutoresizingMaskIntoConstraints = false
        
        chatContainer.addSubview(messageList)
        chatContainer.addSubview(messageComposer)
        
        messageList.translatesAutoresizingMaskIntoConstraints = false
        messageComposer.translatesAutoresizingMaskIntoConstraints = false
        
        NSLayoutConstraint.activate([
            // Chat container takes bottom half of screen
            chatContainer.leadingAnchor.constraint(equalTo: view.leadingAnchor, constant: 16),
            chatContainer.trailingAnchor.constraint(equalTo: view.trailingAnchor, constant: -16),
            chatContainer.bottomAnchor.constraint(equalTo: view.safeAreaLayoutGuide.bottomAnchor, constant: -16),
            chatContainer.heightAnchor.constraint(equalTo: view.heightAnchor, multiplier: 0.4),
            
            // Message list
            messageList.topAnchor.constraint(equalTo: chatContainer.topAnchor),
            messageList.leadingAnchor.constraint(equalTo: chatContainer.leadingAnchor),
            messageList.trailingAnchor.constraint(equalTo: chatContainer.trailingAnchor),
            messageList.bottomAnchor.constraint(equalTo: messageComposer.topAnchor),
            
            // Composer
            messageComposer.leadingAnchor.constraint(equalTo: chatContainer.leadingAnchor),
            messageComposer.trailingAnchor.constraint(equalTo: chatContainer.trailingAnchor),
            messageComposer.bottomAnchor.constraint(equalTo: chatContainer.bottomAnchor)
        ])
    }
    
    private func fetchSupportUser() {
        CometChat.getUser(UID: "support-agent") { [weak self] user in
            guard let user = user else { return }
            DispatchQueue.main.async {
                self?.supportUser = user
                self?.messageList.set(user: user)
                self?.messageList.set(controller: self)        // mandatory — see cometchat-ios-components § 4/§ 6
                self?.messageComposer.set(user: user)
                self?.messageComposer.set(controller: self)    // mandatory — enables attachments/sheets
            }
        } onError: { error in
            print("Error: \(error?.errorDescription ?? "")")
        }
    }
}

Best Practices

1. Always wrap in UINavigationController when presenting CometChat view controllers
2. Hide tab bar when pushing messages using hidesBottomBarWhenPushed = true
3. Handle keyboard properly — CometChat components handle this automatically
4. Support both orientations — components adapt to orientation changes
5. Test on iPad — use split view for better iPad experience
6. Handle deep links — navigate to specific conversations from push notifications