> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-angular-v5-docs-update.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
| 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](/ui-kit/ios/getting-started).
***
## 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:
```swift title="V4 UI Kit" theme={null}
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:
```swift title="V5 UI Kit" theme={null}
// 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](/ui-kit/ios/theme-introduction)
* [Color Customization](/ui-kit/ios/color-resources)
***
## 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
Fresh v5 setup guide for iOS
Explore all v5 prebuilt UI components
New direct property-based theming system
Customize colors and dark mode