Customizing Your UI Kit Builder

Customize iOS UI Kit Builder components with CometChatBuilderSettings, themes, feature toggles, and UI behavior.

The CometChatBuilderSettings object handles feature toggles and styling configuration. For deeper customizations, you can access settings directly and apply them to CometChat UI components.

---

Understanding the Customization Architecture

The iOS UI Kit Builder uses the following for customization:

Component	Purpose	When to Modify
CometChatBuilderSettings	Feature flags and configuration loaded from JSON	Functional changes (enable/disable features)
CometChatTheme	Theme colors and styling	UI/visual changes (colors)
CometChatTypography	Font family and text styling	Typography changes

CometChatBuilderSettings is loaded from your cometchat-builder-settings.json file at app launch using CometChatBuilderSettings.loadFromJSON().

---

Applying Theme Settings

Apply your Builder configuration to CometChat theme at app launch:

import CometChatBuilder

func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

    // Load JSON config
    CometChatBuilderSettings.loadFromJSON()

    // Apply brand color
    CometChatTheme.primaryColor = UIColor.dynamicColor(
        lightModeColor: UIColor(hex: CometChatBuilderSettings.shared.style.color.brandColor),
        darkModeColor: UIColor(hex: CometChatBuilderSettings.shared.style.color.brandColor)
    )
    
    // Apply text colors
    CometChatTheme.textColorPrimary = UIColor.dynamicColor(
        lightModeColor: UIColor(hex: CometChatBuilderSettings.shared.style.color.primaryTextLight),
        darkModeColor: UIColor(hex: CometChatBuilderSettings.shared.style.color.primaryTextDark)
    )
    
    CometChatTheme.textColorSecondary = UIColor.dynamicColor(
        lightModeColor: UIColor(hex: CometChatBuilderSettings.shared.style.color.secondaryTextLight),
        darkModeColor: UIColor(hex: CometChatBuilderSettings.shared.style.color.secondaryTextDark)
    )
    
    // Apply typography
    CometChatTypography.customFontFamilyName = CometChatBuilderSettings.shared.style.typography.font

    return true
}

---

Accessing Feature Flags

You can access feature flags directly from CometChatBuilderSettings.shared:

Chat Features

import CometChatBuilder

// Core Messaging Experience
let typingEnabled = CometChatBuilderSettings.shared.chatFeatures.coreMessagingExperience.typingIndicator
let threadsEnabled = CometChatBuilderSettings.shared.chatFeatures.coreMessagingExperience.threadConversationAndReplies
let photosEnabled = CometChatBuilderSettings.shared.chatFeatures.coreMessagingExperience.photosSharing

// Deeper User Engagement
let mentionsEnabled = CometChatBuilderSettings.shared.chatFeatures.deeperUserEngagement.mentions
let reactionsEnabled = CometChatBuilderSettings.shared.chatFeatures.deeperUserEngagement.reactions
let pollsEnabled = CometChatBuilderSettings.shared.chatFeatures.deeperUserEngagement.polls

// AI User Copilot
let smartReplyEnabled = CometChatBuilderSettings.shared.chatFeatures.aiUserCopilot.smartReply
let conversationStarterEnabled = CometChatBuilderSettings.shared.chatFeatures.aiUserCopilot.conversationStarter

// Group Management
let createGroupEnabled = CometChatBuilderSettings.shared.chatFeatures.groupManagement.createGroup
let deleteGroupEnabled = CometChatBuilderSettings.shared.chatFeatures.groupManagement.deleteGroup

// Moderator Controls
let kickUsersEnabled = CometChatBuilderSettings.shared.chatFeatures.moderatorControls.kickUsers
let banUsersEnabled = CometChatBuilderSettings.shared.chatFeatures.moderatorControls.banUsers

Call Features

// Voice and Video Calling
let voiceCallEnabled = CometChatBuilderSettings.shared.callFeatures.voiceAndVideoCalling.oneOnOneVoiceCalling
let videoCallEnabled = CometChatBuilderSettings.shared.callFeatures.voiceAndVideoCalling.oneOnOneVideoCalling
let groupVideoEnabled = CometChatBuilderSettings.shared.callFeatures.voiceAndVideoCalling.groupVideoConference
let groupVoiceEnabled = CometChatBuilderSettings.shared.callFeatures.voiceAndVideoCalling.groupVoiceConference

Layout Settings

// Layout
let withSidebar = CometChatBuilderSettings.shared.layout.withSideBar
let tabs = CometChatBuilderSettings.shared.layout.tabs
let chatType = CometChatBuilderSettings.shared.layout.chatType

Style Settings

// Style
let theme = CometChatBuilderSettings.shared.style.theme
let brandColor = CometChatBuilderSettings.shared.style.color.brandColor
let font = CometChatBuilderSettings.shared.style.typography.font
let fontSize = CometChatBuilderSettings.shared.style.typography.size

---

Conditional Feature Implementation

Use feature flags to conditionally show/hide UI elements:

import CometChatBuilder

class MessagesViewController: UIViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Conditionally show voice call button
        if CometChatBuilderSettings.shared.callFeatures.voiceAndVideoCalling.oneOnOneVoiceCalling {
            setupVoiceCallButton()
        }
        
        // Conditionally show video call button
        if CometChatBuilderSettings.shared.callFeatures.voiceAndVideoCalling.oneOnOneVideoCalling {
            setupVideoCallButton()
        }
        
        // Conditionally enable reactions
        if CometChatBuilderSettings.shared.chatFeatures.deeperUserEngagement.reactions {
            enableReactions()
        }
    }
}

---

Customizing Colors Programmatically

You can customize colors beyond the JSON configuration:

import CometChatUIKitSwift

// Override primary color
CometChatTheme.primaryColor = UIColor.systemBlue

// Override text colors
CometChatTheme.textColorPrimary = UIColor.dynamicColor(
    lightModeColor: .black,
    darkModeColor: .white
)

CometChatTheme.textColorSecondary = UIColor.dynamicColor(
    lightModeColor: .gray,
    darkModeColor: .lightGray
)

// Override background colors
CometChatTheme.backgroundColor01 = UIColor.dynamicColor(
    lightModeColor: .white,
    darkModeColor: .black
)

---

Customizing Typography

Customize fonts and text styling:

import CometChatUIKitSwift

// Set custom font family
CometChatTypography.customFontFamilyName = "Helvetica"

This is the same CometChatTypography.customFontFamilyName property the JSON loader sets from style.typography.font. For the full typography and font-scaling API, see Theming.

---

Component-Level Customizations

Message List Configuration

Map Builder feature flags onto the message list’s visibility properties. Reactions and in-thread replies are controlled by hideReactionOption and hideReplyInThreadOption:

import CometChatUIKitSwift

let messageListConfiguration = MessageListConfiguration()

// Hide the reaction option when reactions are disabled in the Builder
messageListConfiguration.hideReactionOption =
    !CometChatBuilderSettings.shared.chatFeatures.deeperUserEngagement.reactions

// Hide the "reply in thread" option when threads are disabled in the Builder
messageListConfiguration.hideReplyInThreadOption =
    !CometChatBuilderSettings.shared.chatFeatures.coreMessagingExperience.threadConversationAndReplies

let messagesVC = CometChatMessages()
messagesVC.set(messageListConfiguration: messageListConfiguration)

Message Composer Configuration

import CometChatUIKitSwift

let composerConfiguration = MessageComposerConfiguration()

// Hide the attachment button when no media sharing is enabled in the Builder
composerConfiguration.hideAttachmentButton = !(
    CometChatBuilderSettings.shared.chatFeatures.coreMessagingExperience.photosSharing ||
    CometChatBuilderSettings.shared.chatFeatures.coreMessagingExperience.videoSharing ||
    CometChatBuilderSettings.shared.chatFeatures.coreMessagingExperience.fileSharing
)

// Hide the voice recording button when voice notes are disabled in the Builder
composerConfiguration.hideVoiceRecordingButton =
    !CometChatBuilderSettings.shared.chatFeatures.deeperUserEngagement.voiceNotes

let messagesVC = CometChatMessages()
messagesVC.set(messageComposerConfiguration: composerConfiguration)

These properties are part of the standard iOS UI Kit. For the full list of configurable options on each component, see Message List and Message Composer.

---

Modifying the JSON Configuration

To change feature settings, edit your cometchat-builder-settings.json file:

{
  "settings": {
    "chatFeatures": {
      "coreMessagingExperience": {
        "typingIndicator": true,
        "photosSharing": false,  // Disable photo sharing
        "videoSharing": false    // Disable video sharing
      },
      "deeperUserEngagement": {
        "reactions": true,
        "polls": false           // Disable polls
      }
    },
    "style": {
      "theme": "dark",           // Force dark mode
      "color": {
        "brandColor": "#FF5733"  // Custom brand color
      }
    }
  }
}

Changes to the JSON file require rebuilding the app to take effect.

---

Parallel Customization Layers

The Builder settings sit on top of the standard CometChat iOS UI Kit, so every UI Kit customization layer is still available to you. Reach for these when the JSON style block and feature toggles aren’t enough:

Theme

Global colors, typography, and dark mode via CometChatTheme and CometChatTypography.

Component Styling

Style individual components (header, list, composer) with style classes, globally or per instance.

Message Template

Define custom message bubbles with your own content, header, and reply views.

Components Overview

Every prebuilt component and its configuration object.

---

Next Steps

UI Kit Builder Settings

Understand all available feature toggles and configuration options.

Components Overview

Explore all available UI components and their customization options.

Theming

Deep dive into colors, typography, and advanced styling.

Directory Structure

Understand how the exported code is organized.