Upgrading from V4 to V5

Migration guide for upgrading from CometChat iOS UI Kit v4 to v5 with breaking changes, property updates, and new patterns.

AI Integration Quick Reference

Field	Value
Package	CometChatUIKitSwift
Architecture	Composite components replaced with modular components
Theming	Direct static property assignment on CometChatTheme and CometChatTypography
Key changes	CometChatConversationsWithMessages → Individual components (CometChatConversations, CometChatMessageHeader, CometChatMessageList, CometChatMessageComposer)
Style props	Removed — use native theming system with direct property access
Config props	Removed — direct control over each component

The CometChat v5 iOS UI Kit introduces a modular architecture with smaller, focused components replacing composite components. This guide outlines the key differences and provides migration steps from v4 to v5.

---

Overview of Changes

Feature	v4	v5
Architecture	Composite components (e.g., CometChatConversationsWithMessages)	Modular components (CometChatConversations, CometChatMessageList, etc.)
Theming	CometChatTheme with Palette and Typography classes	Direct static property assignment
Customization	Complex configuration objects	Direct component properties and Swift APIs
Style Props	Inline style properties	Native theming system
Custom Views	itemView, leadingView, trailingView, subtitleView, titleView	Unified naming convention across components

---

Integration

In v4, integration was straightforward due to composite components like CometChatConversationsWithMessages. This single component provided end-to-end functionality including listing conversations, handling clicks, loading messages, and supporting threaded messages. However, customization required deep understanding of internal flows, and configurations mixed custom view props, behavioral props, and style props.

With v5, composite components are replaced with smaller, modular components:

• CometChatConversations
• CometChatMessageHeader
• CometChatMessageList
• CometChatMessageComposer

This modular approach makes integration more flexible. Each component has a well-defined purpose, and developers can customize behavior and styling directly via component properties and Swift APIs.

Learn how to build a complete messaging UI using the v5 UI Kit by following the Getting Started guide.

---

Components

v4 Components

CometChatConversationsWithMessages	CometChatUsersWithMessages	CometChatGroupsWithMessages
CometChatMessages	CometChatMessageHeader	CometChatMessageList
CometChatMessageComposer	CometChatThreadedMessages	CometChatConversations
CometChatUsers	CometChatGroups	CometChatContacts
CometChatDetails	CometChatGroupMembers	CometChatAddMembers
CometChatBannedMembers	CometChatTransferOwnership	CometChatMessageInformation
CometChatIncomingCall	CometChatOngoingCall	CometChatOutgoingCall
CometChatCallButtons	CometChatCallLogs	CometChatCallLogDetails
CometChatCallLogHistory

v5 Components

CometChatConversations	CometChatUsers	CometChatGroups
CometChatGroupMembers	CometChatMessageHeader	CometChatMessageList
CometChatMessageComposer	CometChatThreadedMessageHeader	CometChatIncomingCall
CometChatOutgoingCall	CometChatCallButtons	CometChatCallLogs

---

Theming

v4 Theming

In v4, theming required instantiating multiple objects and passing them through constructors:

V4 UI Kit

let palette = Palette()
palette.set(background: .purple)
palette.set(accent: .cyan)
palette.set(primary: .green)
palette.set(error: .red)
palette.set(success: .yellow)
palette.set(secondary: .orange)

let family = CometChatFontFamily(
    regular: "CourierNewPSMT",
    medium: "CourierNewPS-BoldMT",
    bold: "CourierNewPS-BoldMT"
)
var typography = Typography()
typography.overrideFont(family: family)

let theme = CometChatTheme(typography: typography, palatte: palette)

v5 Theming

In v5, theming uses direct static property assignment:

V5 UI Kit

// Apply the global theme - typically in AppDelegate or SceneDelegate
CometChatTheme.primaryColor = UIColor.red
CometChatTheme.backgroundColor01 = .brown
CometChatTheme.backgroundColor02 = .green

// Apply custom typography
CometChatTypography.Body.regular = UIFont.systemFont(ofSize: 18, weight: .bold)

For detailed guidance on theming, refer to:

• Theming Documentation
• Color Customization

---

Properties

In v5, the approach to properties has been refined:

• Style properties — Replaced by a native theming system based on direct property access
• Configuration properties — Removed due to modular architecture; developers have direct control over each component
• Custom view properties — Restructured for consistency with unified naming: itemView, leadingView, trailingView, subtitleView, titleView

---

Property Changes

Conversations

New Properties

Name	Type	Description
hideNavigationBar	Bool	Hides or shows the navigation bar
hideSearch	Bool	Hides the search bar
hideLoadingState	Bool	Hides the loading state indicator
hideDeleteConversationOption	Bool	Hides the option to delete a conversation
hideGroupType	Bool	Hides the group type indicator
backgroundDrawable	UIImage	Sets a background image
separatorColor	UIColor	Sets the color of separators
separatorWidth	CGFloat	Sets the width of separators
errorTextColor	UIColor	Sets the color of error messages
lastMessageTextColor	UIColor	Sets the color of the last message text
typingIndicatorColor	UIColor	Sets the color of the typing indicator
dateTimeFormatter	CometChatDateTimeFormatter	Customizes date/time display
set(OnItemLongClick:)	Method	Triggered on long press
set(onEmpty:)	Method	Triggered when list is empty

Renamed Properties

v4 Name	v5 Name	Description
hide(error: Bool)	hideErrorView	Hides the error state view
show(backButton: Bool)	hideBackButton	Controls back button visibility (logic inverted)
hide(receipt: Bool)	hideReceipts	Hides message receipts
disable(userPresence: Bool)	hideUserStatus	Hides online/offline status
setOnItemClick	set(OnItemClick:)	Triggered on click
setOnBack	set(onBack:)	Override back button action
setOnSelection	set(onSelection:)	Triggered on selection
setOnError	set(onError:)	Override error action

Removed Properties

Name	Description
hide(separator: Bool)	Replaced by style properties
disable(typing: Bool)	Toggled typing indicator visibility
setDatePattern	Replaced by dateTimeFormatter
protectedGroupIcon	Icon for password protected groups
sentIcon, deliveredIcon, readIcon	Receipt icons

---

Users

New Properties

Name	Type	Description
set(options:)	(User) -> [CometChatUserOption]	Custom options for each user
set(leadingView:)	(User) -> UIView	Custom leading view
set(titleView:)	(User) -> UIView	Custom title view
set(trailView:)	(User) -> UIView	Custom trailing view
set(onEmpty:)	() -> Void	Triggered when list is empty
hideErrorView	Bool	Hides the error state view
hideNavigationBar	Bool	Hides the navigation bar
hideBackButton	Bool	Hides the back button
hideLoadingState	Bool	Hides loading indicator
hideUserStatus	Bool	Hides online/offline status
hideSectionHeader	Bool	Hides section headers
hideSearch	Bool	Hides the search bar

Renamed Properties

v4 Name	v5 Name	Description
setListItemView	set(listItemView:)	Custom list item view
setSubtitleView	set(subtitleView:)	Custom subtitle view
setEmptyStateView	set(emptyView:)	Custom empty state view
setErrorStateView	set(errorView:)	Custom error state view
setOnItemClick	set(onItemClick:)	Triggered on click
setOnItemLongClick	set(onItemLongClick:)	Triggered on long press
setOnBack	set(onBack:)	Triggered on back press
setOnSelection	set(onSelection:)	Triggered on selection
setOnError	set(onError:)	Triggered on error

Removed Properties

Name	Description
set(loadingStateView:)	Set loading view icon size
hide(errorText:)	Hide error text
show(backButton:)	Toggle back button
set(searchIcon:)	Set search icon
hide(search:)	Toggle search box
hide(separator:)	Hide divider
disable(userPresence:)	Control online indicator
set(emptyStateText:)	Custom empty text
set(errorStateText:)	Custom error text
set(searchPlaceholder:)	Search placeholder
set(title:mode:)	Set title with display mode
setOnLoad	Triggered when list is fetched

---

Groups

New Properties

Name	Type	Description
set(onSelection:)	Closure	Returns selected groups
set(onEmpty:)	Closure	Triggered when list is empty
setOnLoad	Closure	Triggered when list is fetched
listItemSelectedImage	UIImage	Selected checkbox image
listItemDeSelectedImage	UIImage	Deselected checkbox image
hideErrorView	Bool	Hides error state view
hideNavigationBar	Bool	Hides navigation bar
hideSearch	Bool	Hides search bar
hideBackButton	Bool	Hides back button
hideLoadingState	Bool	Hides loading indicator
set(leadingView:)	(Group?) -> UIView	Custom leading view
set(titleView:)	(Group?) -> UIView	Custom title view
set(trailView:)	(Group?) -> UIView	Custom trailing view

Renamed Properties

v4 Name	v5 Name	Description
SetOnItemClick	set(onItemClick:)	Triggered on click
SetOnItemLongClick	set(OnItemLongClick:)	Triggered on long press
SetOnError	set(onError:)	Triggered on error
SetOnBack	set(onBack:)	Triggered on back press
setListItemView	SetListItemView	Custom list item
setSubtitleView	SetSubTitleView	Custom subtitle view

---

Group Members

New Properties

Name	Type	Description
hideError	Bool	Hides error state view
hideUserStatus	Bool	Hides online/offline status
hideNavigationBar	Bool	Hides navigation bar
hideLoadingState	Bool	Hides loading indicator
hideBackIcon	Bool	Hides back button
hideKickMemberOption	Bool	Hides kick member option
hideBanMemberOption	Bool	Hides ban member option
hideScopeChangeOption	Bool	Hides scope change option
hideSearch	Bool	Hides search bar
set(onSelection:)	([GroupMember]) -> Void	Returns selected members
set(onEmpty:)	() -> Void	Triggered when list is empty
set(onLoad:)	([GroupMember]) -> Void	Triggered when list is fetched
set(leadingView:)	(GroupMember?) -> UIView	Custom leading view
set(titleView:)	(GroupMember?) -> UIView	Custom title view

Renamed Properties

v4 Name	v5 Name	Description
background	backgroundColor	Background color
disable(userPresence:)	hideUserStatus	Hides online/offline status
hide(search:)	hideSearch	Hides search bar
setOnItemClick	set(onItemClick:)	Triggered on click
setOnItemLongClick	set(onItemLongClick:)	Triggered on long press
setOnError	set(onError:)	Triggered on error
setOnBack	set(onBack:)	Triggered on back press

Removed Properties

Name	Description
backIconTint	Back button tint color
searchIconTint	Search icon tint color
avatarStyle	Avatar component styles
statusIndicatorStyle	Status indicator styles
listItemStyle	List item view styles
groupScopeStyle	Change scope component styles
groupMembersStyle	Component styles
set(title:mode:)	Custom title
set(backButtonTitle:)	Back button text
set(searchPlaceholder:)	Search placeholder
show(backButton:)	Show back button
set(errorStateText:)	Error state text
selectionMode(mode:)	Selection mode
hide(separator:)	Hide separator

---

Message Header

New Properties

Name	Type	Description
titleTextColor	UIColor	Header title text color
titleTextFont	UIFont	Header title font
subtitleTextColor	UIColor	Subtitle text color
subtitleTextFont	UIFont	Subtitle font
backButtonImageTintColor	UIColor	Back button tint
hideBackButton	Bool	Hides back button
hideUserStatus	Bool	Hides user status
hideVideoCallButton	Bool	Hides video call button
hideVoiceCallButton	Bool	Hides voice call button
set(onBack:)	() -> Void	Triggered on back press
set(onError:)	(CometChatException) -> Void	Triggered on error
set(listItemView:)	(User?, Group?) -> UIView	Custom list item
set(leadingView:)	(User?, Group?) -> UIView	Custom leading view
set(titleView:)	(User?, Group?) -> UIView	Custom title view
set(trailView:)	(User?, Group?) -> UIView	Custom trailing view
set(subtitleView:)	(User?, Group?) -> UIView	Custom subtitle view
dateTimeFormatter	CometChatDateTimeFormatter	Date/time formatting

Renamed Properties

v4 Name	v5 Name	Description
background	backgroundColor	Background color
backIconTint	backButtonImageTintColor	Back button tint
hide(backButton:)	hideBackButton	Hides back button
set(disableUsersPresence:)	hideUserStatus	Hides user status
setMenus	set(menus:)	Custom menus
setSubtitleView	set(subtitleView:)	Custom subtitle view

Removed Properties

Name	Description
typingIndicatorTextFont	Typing indicator font
typingIndicatorTextColor	Typing indicator color
detailIconTint	Detail icon tint
onlineStatusColor	Online status color
set(protectedGroupIcon:)	Protected group icon
set(privateGroupIcon:)	Private group icon
disable(typing:)	Enable/disable typing indicators

---

Message List

New Properties

Name	Type	Description
hideAvatar	Bool	Hides sender avatar
hideGroupActionMessages	Bool	Hides group action messages
hideReplyInThreadOption	Bool	Hides reply in thread option
hideTranslateMessageOption	Bool	Hides translation option
hideEditMessageOption	Bool	Hides edit option
hideDeleteMessageOption	Bool	Hides delete option
hideReactionOption	Bool	Hides reaction option
hideMessagePrivatelyOption	Bool	Hides message privately option
hideCopyMessageOption	Bool	Hides copy option
hideMessageInfoOption	Bool	Hides message info option
hideHeaderView	Bool	Hides header view
hideFooterView	Bool	Hides footer view
hideDateSeparator	Bool	Hides date separator
scrollToBottomOnNewMessages	Bool	Scrolls to bottom on new messages
hideReceipts	Bool	Hides read receipts
disableSoundForMessages	Bool	Disables message sound
hideEmptyView	Bool	Hides empty state view
hideErrorView	Bool	Hides error view
hideLoadingView	Bool	Hides loading view
hideNewMessageIndicator	Bool	Hides new message indicator
set(onThreadRepliesClick:)	(BaseMessage, CometChatMessageTemplate) -> Void	Thread click callback
set(onReactionClick:)	(CometChat.ReactionCount, BaseMessage?) -> Void	Reaction click callback
set(onError:)	(CometChatException) -> Void	Error callback
set(onEmpty:)	() -> Void	Empty state callback
set(onLoad:)	([BaseMessage]) -> Void	Load callback
set(headerView:)	UIView	Custom header view
set(footerView:)	UIView	Custom footer view
set(textFormatters:)	[CometChatTextFormatter]	Text formatters
dateTimeFormatter	CometChatDateTimeFormatter	Date/time formatting

Renamed Properties

v4 Name	v5 Name	Description
hide(receipt:)	hideReceipts	Hides receipts
show(avatar:)	hideAvatar	Shows/hides avatar
background	backgroundColor	Background color
alignment	set(messageAlignment:)	Message alignment

Removed Properties

Name	Description
loadingIconTint	Loading icon tint
emptyTextFont	Empty state text font
errorTextFont	Error text font
emptyTextColor	Empty state text color
errorTextColor	Error state text color
nameTextColor	Sender name text color
nameTextFont	Sender name font
timestampTextColor	Timestamp text color
threadReplySeperatorColor	Thread reply separator color
threadReplyTextColor	Thread reply text color
threadReplyTextFont	Thread reply font
hide(error:)	Hide error view
messageInformationConfiguration	Message info configuration
reactionsConfiguration	Reactions configuration
setDateSeparatorPattern	Date separator pattern
setDatePattern	Date pattern

---

Message Composer

New Properties

Name	Type	Description
placeHolderTextFont	UIFont	Placeholder font
placeHolderTextColor	UIColor	Placeholder color
textFiledColor	UIColor	Input text color
textFiledFont	UIFont	Input text font
sendButtonImage	UIImage	Send button icon
sendButtonImageTint	UIColor	Send button tint
activeSendButtonImageBackgroundColor	UIColor	Active send button background
inactiveSendButtonImageBackgroundColor	UIColor	Inactive send button background
attachmentImage	UIImage	Attachment button icon
attachmentImageTint	UIColor	Attachment button tint
voiceRecordingImage	UIImage	Voice recording icon
voiceRecordingImageTint	UIColor	Voice recording tint
aiImage	UIImage	AI button icon
aiImageTint	UIColor	AI button tint
stickerImage	UIImage	Sticker button icon
stickerTint	UIColor	Sticker button tint
disableTypingEvents	Bool	Disables typing indicators
disableMentions	Bool	Disables mentions
hideImageAttachmentOption	Bool	Hides image attachment
hideVideoAttachmentOption	Bool	Hides video attachment
hideAudioAttachmentOption	Bool	Hides audio attachment
hideFileAttachmentOption	Bool	Hides file attachment
hidePollsOption	Bool	Hides polls option
hideCollaborativeDocumentOption	Bool	Hides collaborative document
hideCollaborativeWhiteboardOption	Bool	Hides collaborative whiteboard
hideAttachmentButton	Bool	Hides attachment button
hideVoiceRecordingButton	Bool	Hides voice recording button
hideStickersButton	Bool	Hides stickers button
hideSendButton	Bool	Hides send button
set(onSendButtonClick:)	(BaseMessage) -> Void	Send button callback
set(onTextChangedListener:)	(String) -> Void	Text change callback
set(onError:)	(CometChatException) -> Void	Error callback
set(attachmentOptions:)	(User?, Group?, UIViewController?) -> [CometChatMessageComposerAction]	Custom attachment options
set(sendButtonView:)	(User?, Group?) -> UIView	Custom send button
set(headerView:)	(User?, Group?) -> UIView	Custom header view
set(footerView:)	(User?, Group?) -> UIView	Custom footer view
set(textFormatter:)	[CometChatTextFormatter]	Text formatters
mediaRecorderStyle	MediaRecorderStyle	Media recording styling
aiOptionsStyle	AIOptionsStyle	AI options styling

Renamed Properties

v4 Name	v5 Name	Description
background	backgroundColor	Background color
hide(voiceRecording:)	hideVoiceRecordingButton	Hides voice recording
disable(disableTypingEvents:)	disableTypingEvents	Disables typing events
disable(disableSoundForMessages:)	disableSoundForMessages	Disables message sound
setMentionsFormatters	set(textFormatter:)	Text formatters

Removed Properties

Name	Description
inputBackground	Input background color
textFont	Input text font
inputBoxPlaceholderFont	Placeholder font
attachmentIconTint	Attachment icon tint
sendIconTint	Send icon tint
separatorTint	Separator color
inputBorderWidth	Input border width
inputBorderColor	Input border color
actionSheetTitleColor	Action sheet title color
actionSheetTitleFont	Action sheet title font
voiceRecordingIconTint	Voice recording icon tint
aiIconTint	AI icon tint
set(background:)	Background color
set(placeholderText:)	Placeholder text
set(maxLines:)	Max lines
set(auxiliaryButtonAlignment:)	Auxiliary button position
set(customSoundForMessage:)	Custom message sound
set(liveReactionIconURL:)	Live reaction icon
set(disableMentions:)	Disable mentions
setOnSendButtonClick	Send button callback
hide(liveReaction:)	Hide live reaction
hide(footerView:)	Hide footer view
hide(headerView:)	Hide header view
hide(sendButton:)	Hide send button
setAttachmentOptions	Attachment options
setAuxilaryButtonView	Auxiliary button view
setSecondaryButtonView	Secondary button view
setSendButtonView	Send button view

---

Next Steps

Getting Started

Fresh v5 setup guide for iOS

Components Overview

Explore all v5 prebuilt UI components

Theme Introduction

New direct property-based theming system

Color Resources

Customize colors and dark mode