> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-rn-guide-message-privately.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Search
> Search CometChat iOS UI Kit conversations and messages with filters, scoped results, request builders, and selection callbacks.
The `CometChatSearch` component is a powerful and customizable search interface that allows users to search across conversations and messages in real time. It supports a wide variety of filters, scopes, and customization options.
```json theme={null}
{
"component": "CometChatSearch",
"package": "CometChatUIKitSwift",
"import": "import CometChatUIKitSwift\nimport CometChatSDK",
"description": "Provides search functionality across conversations and messages",
"inherits": "UIViewController",
"primaryOutput": {
"callback": "onMessageClicked",
"type": "(BaseMessage) -> Void"
},
"props": {
"data": {
"user": { "type": "User?", "default": "nil", "note": "Limits search to specific user" },
"group": { "type": "Group?", "default": "nil", "note": "Limits search to specific group" },
"conversationsRequestBuilder": { "type": "ConversationsRequest.ConversationsRequestBuilder", "default": "SDK default" },
"messagesRequestBuilder": { "type": "MessagesRequest.MessageRequestBuilder", "default": "SDK default" }
},
"callbacks": {
"onConversationClicked": "(Conversation, IndexPath) -> Void",
"onMessageClicked": "(BaseMessage) -> Void",
"onBack": "() -> Void",
"onError": "(CometChatException) -> Void",
"onEmpty": "() -> Void"
},
"visibility": {
"hideNavigationBar": { "type": "Bool", "default": false },
"hideBackButton": { "type": "Bool", "default": false },
"hideUserStatus": { "type": "Bool", "default": false },
"hideGroupType": { "type": "Bool", "default": false },
"hideReceipts": { "type": "Bool", "default": false }
},
"search": {
"searchFilters": { "type": "[SearchFilter]", "default": "All available filters" },
"initialSearchFilter": { "type": "SearchFilter?", "default": "nil" },
"searchIn": { "type": "[SearchScope]", "default": "[.conversations, .messages]" }
},
"viewSlots": {
"listItemViewForConversation": "(Conversation) -> UIView",
"leadingViewForConversation": "(Conversation) -> UIView",
"titleViewForConversation": "(Conversation) -> UIView",
"subtitleViewForConversation": "(Conversation) -> UIView",
"tailViewForConversation": "(Conversation) -> UIView",
"listItemViewForMessage": "(BaseMessage) -> UIView",
"leadingViewForMessage": "(BaseMessage) -> UIView",
"titleViewForMessage": "(BaseMessage) -> UIView",
"subtitleViewForMessage": "(BaseMessage) -> UIView",
"trailingViewForMessage": "(BaseMessage) -> UIView",
"initialView": "UIView",
"loadingView": "UIView",
"emptyView": "UIView",
"errorView": "UIView"
}
},
"events": [],
"sdkListeners": [],
"compositionExample": {
"description": "Search is typically accessed from conversation list or message header",
"components": ["CometChatConversations", "CometChatSearch", "CometChatMessages"],
"flow": "User taps search → enters query → taps result → navigates to conversation/message"
}
}
```
| Field | Value |
| --------- | --------------------- |
| Component | `CometChatSearch` |
| Package | `CometChatUIKitSwift` |
| Inherits | `UIViewController` |
***
## Usage
### Integration
`CometChatSearch` is a composite component that offers flexible integration options. It can be launched directly via button clicks or any user-triggered action.
```swift lines theme={null}
import CometChatUIKitSwift
let search = CometChatSearch()
self.navigationController?.pushViewController(search, animated: true)
```
***
### Actions
[Actions](/ui-kit/ios/components-overview#actions) dictate how a component functions. They are divided into two types: Predefined and User-defined. You can override either type to tailor the behavior to fit your specific needs.
#### 1. onConversationClicked
Triggered when you click on a Conversation from the search result. This action doesn't have a predefined behavior—you can override it using the following code snippet:
```swift lines theme={null}
import CometChatUIKitSwift
let search = CometChatSearch()
search.onConversationClicked = { conversation, indexPath in
print("Conversation clicked:", conversation.conversationId)
}
```
***
#### 2. onMessageClicked
Triggered when you click on a Message from the search result. This action doesn't have a predefined behavior—you can override it using the following code snippet:
```swift lines theme={null}
import CometChatUIKitSwift
let search = CometChatSearch()
search.onMessageClicked = { message in
print("Message clicked:", message.id)
}
```
***
#### 3. onBack
Triggered when you click on the back button of the search component.
```swift lines theme={null}
import CometChatUIKitSwift
let search = CometChatSearch()
search.onBack = {
self.navigationController?.popViewController(animated: true)
}
```
***
#### 4. onError
Listens for any errors that occur in the Search component. This action doesn't change the component's behavior.
```swift lines theme={null}
import CometChatUIKitSwift
let search = CometChatSearch()
search.set(onError: { error in
print("Search error:", error.localizedDescription)
})
```
***
#### 5. onEmpty
Listens for the empty state of the Search component. This action doesn't change the component's behavior.
```swift lines theme={null}
import CometChatUIKitSwift
let search = CometChatSearch()
search.set(onEmpty: {
print("No results found")
})
```
***
### Filters
Filters allow you to customize the data displayed in a list within a Component. You can filter the list based on your specific criteria using RequestBuilders of the Chat SDK.
#### SearchScope
The `SearchScope` enum defines what types of content to search:
| Value | Description |
| ---------------- | ----------------------- |
| `.conversations` | Search in conversations |
| `.messages` | Search in messages |
```swift lines theme={null}
import CometChatUIKitSwift
let search = CometChatSearch()
// Search only in messages
search.set(searchIn: [.messages])
// Search in both conversations and messages (default)
search.set(searchIn: [.conversations, .messages])
```
#### SearchFilter
The `SearchFilter` enum defines available filter options:
| Value | Description |
| ------------ | ----------------------------- |
| `.unread` | Filter by unread items |
| `.groups` | Filter by group conversations |
| `.photos` | Filter by photo messages |
| `.videos` | Filter by video messages |
| `.links` | Filter by link messages |
| `.documents` | Filter by document messages |
| `.audio` | Filter by audio messages |
```swift lines theme={null}
import CometChatUIKitSwift
let search = CometChatSearch()
// Set available filters with an initial selection
search.set(searchFilters: [.unread, .groups, .photos, .videos], initialFilter: .photos)
```
#### 1. ConversationsRequestBuilder
Set the `ConversationsRequestBuilder` in the Search Component to filter the search results. For more options, refer to [ConversationRequestBuilder](/sdk/ios/retrieve-conversations).
```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK
let convBuilder = ConversationsRequest.ConversationsRequestBuilder()
.set(limit: 20)
let search = CometChatSearch()
search.set(conversationsRequestBuilder: convBuilder)
```
***
#### 2. MessagesRequestBuilder
Set the `MessagesRequestBuilder` in the Search Component to filter the search results. For more options, refer to [MessagesRequestBuilder](/sdk/ios/additional-message-filtering).
```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK
let msgBuilder = MessagesRequest.MessageRequestBuilder()
.set(limit: 30)
.hide(deletedMessages: true)
let search = CometChatSearch()
search.set(messagesRequestBuilder: msgBuilder)
```
***
### Events
[Events](/ui-kit/ios/components-overview#events) are emitted by a Component. By using events, you can extend existing functionality. Being global events, they can be applied in multiple locations and can be added or removed as needed.
The `CometChatSearch` component does not produce any events.
***
## Customization
To fit your app's design requirements, you can customize the appearance of the `CometChatSearch` component. We provide exposed methods that allow you to modify the experience and behavior according to your specific needs.
### Style
Using Style, you can customize the look and feel of the component in your app. These parameters typically control elements such as the color, size, shape, and fonts used within the component.
```swift lines theme={null}
import CometChatUIKitSwift
// Instance-level styling
let style = SearchStyle()
style.backgroundColor = UIColor(hex: "#EDEAFA")
style.listItemBackground = UIColor(hex: "#EDEAFA")
style.listItemTitleFont = UIFont(name: "TimesNewRomanPS-Regular", size: 16)
style.titleFont = UIFont(name: "TimesNewRomanPS-Bold", size: 12)
style.searchBarPlaceholderTextFont = UIFont(name: "TimesNewRomanPS-Regular", size: 12)
let searchVC = CometChatSearch()
searchVC.style = style
self?.navigationController?.pushViewController(searchVC, animated: true)
// Global-level styling
CometChatSearch.style.backgroundColor = UIColor(hex: "#EDEAFA")
CometChatSearch.style.listItemBackground = UIColor(hex: "#EDEAFA")
CometChatSearch.style.listItemTitleFont = UIFont(name: "TimesNewRomanPS-Regular", size: 16)
CometChatSearch.style.titleFont = UIFont(name: "TimesNewRomanPS-Bold", size: 12)
CometChatSearch.style.searchBarPlaceholderTextFont = UIFont(name: "TimesNewRomanPS-Regular", size: 12)
```
***
### Functionality
These are small functional customizations that allow you to fine-tune the overall experience of the component. With these, you can toggle the visibility of UI elements.
| Property | Description | Example |
| ----------------------- | ------------------------------------------------ | ---------------------------------------------------------- |
| user | Restrict search to a specific user chat | `search.user = user` |
| group | Restrict search to a group | `search.group = group` |
| hideUserStatus | Hide online/offline indicator | `search.hideUserStatus = true` |
| hideGroupType | Hide group type icon | `search.hideGroupType = true` |
| hideBackButton | Hide the back button | `search.hideBackButton = true` |
| hideReceipts | Hide message read/delivery receipt indicators | `search.hideReceipts = true` |
| searchFilters | Filters like "Unread", "Groups", "Photos", etc. | `search.set(searchFilters: [.unread, .groups, .photos])` |
| initialSearchFilter | Default filter to apply on load | `search.set(searchFilters: [...], initialFilter: .photos)` |
| searchIn (searchScopes) | Restrict search: messages / conversations / both | `search.set(searchIn: [.messages, .conversations])` |
| loadingView | Custom loader view | `search.set(loadingView: spinner)` |
| emptyView | Custom empty result view | `search.set(emptyView: emptyView)` |
| errorView | Custom error UI | `search.set(errorView: errorView)` |
| initialView | Custom view before search query is entered | `search.set(initialView: initialView)` |
| disableTyping | Disable typing indicators | `search.disableTyping = true` |
| disableSoundForMessages | Disable message sounds | `search.disableSoundForMessages = true` |
| customSoundForMessages | Custom sound URL for messages | `search.customSoundForMessages = URL(string: "...")` |
***
### Advanced
For advanced-level customization, you can set custom views to the component. This lets you tailor each aspect of the component to fit your exact needs and application aesthetics. You can create and define your own views, layouts, and UI elements and then incorporate those into the component.
#### Conversation View Customization
| Function | Description |
| --------------------------- | ------------------------------------------------- |
| listItemViewForConversation | Assign a custom list item view to a conversation. |
| leadingViewForConversation | Assign a custom leading view to a conversation. |
| titleViewForConversation | Assign a custom title view to a conversation. |
| subtitleViewForConversation | Assign a custom subtitle view to a conversation. |
| tailViewForConversation | Assign a custom trailing view to a conversation. |
```swift lines theme={null}
import CometChatUIKitSwift
let searchVC = CometChatSearch()
searchVC.set(listItemViewForConversation: { conversation in
let customView = UIView()
// Configure custom conversation view
return customView
})
```
#### Message View Customization
With message item view functions, you can assign custom views to different types of messages in the search result. For more information, refer to the [itemView](/ui-kit/ios/message-list#itemview) prop of the `CometChatMessages` component.
Here's how you can override the default message item view with a custom one for text messages:
```swift lines theme={null}
import CometChatUIKitSwift
let searchVC = CometChatSearch()
searchVC.set(listItemViewForMessage: { message in
return SearchMessageItemView()
})
```
Custom view implementation:
```swift lines theme={null}
class SearchMessageItemView: UIView {
// MARK: - UI Components
private let containerView: UIView = {
let view = UIView()
view.backgroundColor = UIColor(red: 0.95, green: 0.93, blue: 0.98, alpha: 1.0)
return view
}()
private let senderLabel: UILabel = {
let label = UILabel()
label.font = UIFont.boldSystemFont(ofSize: 16)
label.textColor = UIColor(red: 0.37, green: 0.22, blue: 0.73, alpha: 1.0)
return label
}()
private let messageLabel: UILabel = {
let label = UILabel()
label.font = UIFont.systemFont(ofSize: 16)
label.textColor = UIColor.darkGray
label.numberOfLines = 1
label.lineBreakMode = .byTruncatingTail
return label
}()
private let bottomLine: UIView = {
let view = UIView()
view.backgroundColor = UIColor(red: 0.37, green: 0.22, blue: 0.73, alpha: 1.0)
return view
}()
private let stack: UIStackView = {
let stack = UIStackView()
stack.axis = .horizontal
stack.spacing = 4
stack.alignment = .center
return stack
}()
// MARK: - Initialization
override init(frame: CGRect) {
super.init(frame: frame)
setupUI()
}
required init?(coder: NSCoder) {
super.init(coder: coder)
setupUI()
}
// MARK: - Setup
private func setupUI() {
addSubview(containerView)
containerView.translatesAutoresizingMaskIntoConstraints = false
containerView.addSubview(stack)
stack.translatesAutoresizingMaskIntoConstraints = false
containerView.addSubview(bottomLine)
bottomLine.translatesAutoresizingMaskIntoConstraints = false
stack.addArrangedSubview(senderLabel)
stack.addArrangedSubview(messageLabel)
NSLayoutConstraint.activate([
containerView.topAnchor.constraint(equalTo: topAnchor),
containerView.leadingAnchor.constraint(equalTo: leadingAnchor),
containerView.trailingAnchor.constraint(equalTo: trailingAnchor),
containerView.bottomAnchor.constraint(equalTo: bottomAnchor),
stack.topAnchor.constraint(equalTo: containerView.topAnchor, constant: 12),
stack.leadingAnchor.constraint(equalTo: containerView.leadingAnchor, constant: 12),
stack.trailingAnchor.constraint(equalTo: containerView.trailingAnchor, constant: -12),
bottomLine.heightAnchor.constraint(equalToConstant: 2),
bottomLine.leadingAnchor.constraint(equalTo: containerView.leadingAnchor),
bottomLine.trailingAnchor.constraint(equalTo: containerView.trailingAnchor),
bottomLine.bottomAnchor.constraint(equalTo: containerView.bottomAnchor)
])
}
// MARK: - Configuration
/// Configure view with sender name and message text
/// - Parameters:
/// - sender: The sender's name
/// - message: The message content
/// - boldKeyword: Optional keyword to highlight in bold
func configure(sender: String, message: String, boldKeyword: String?) {
senderLabel.text = sender + ":"
if let keyword = boldKeyword, message.contains(keyword) {
let attributed = NSMutableAttributedString(string: message)
let range = (message as NSString).range(of: keyword)
attributed.addAttribute(.font, value: UIFont.boldSystemFont(ofSize: 16), range: range)
messageLabel.attributedText = attributed
} else {
messageLabel.text = message
}
}
}
```
Available message item view functions for customization:
| Function | Message Type |
| ----------------------- | ---------------- |
| listItemViewForMessage | Text Message |
| listItemViewForImage | Image Message |
| listItemViewForVideo | Video Message |
| listItemViewForAudio | Audio Message |
| listItemViewForDocument | Document Message |
| listItemViewForLink | Link Message |
```swift lines theme={null}
import CometChatUIKitSwift
let searchVC = CometChatSearch()
// Custom view for image messages
searchVC.set(listItemViewForImage: { mediaMessage in
let customView = UIView()
// Configure custom image message view
return customView
})
// Custom view for video messages
searchVC.set(listItemViewForVideo: { mediaMessage in
let customView = UIView()
// Configure custom video message view
return customView
})
// Custom view for audio messages
searchVC.set(listItemViewForAudio: { mediaMessage in
let customView = UIView()
// Configure custom audio message view
return customView
})
// Custom view for document messages
searchVC.set(listItemViewForDocument: { mediaMessage in
let customView = UIView()
// Configure custom document message view
return customView
})
// Custom view for link messages
searchVC.set(listItemViewForLink: { mediaMessage in
let customView = UIView()
// Configure custom link message view
return customView
})
```
#### Message Granular View Customization
For more granular control over message search results, you can customize individual parts of the message item:
| Function | Description |
| ---------------------- | ------------------------------------------ |
| leadingViewForMessage | Replaces the message avatar / left section |
| titleViewForMessage | Replaces the message title text |
| subtitleViewForMessage | Replaces the message subtitle text |
| trailingViewForMessage | Replaces the message trailing section |
```swift lines theme={null}
import CometChatUIKitSwift
let searchVC = CometChatSearch()
// Custom leading view for messages (avatar area)
searchVC.set(leadingViewForMessage: { message in
let customView = UIView()
customView.backgroundColor = .systemPurple
customView.layer.cornerRadius = 24
// Configure custom leading view
return customView
})
// Custom title view for messages
searchVC.set(titleViewForMessage: { message in
let label = UILabel()
label.text = message.sender?.name ?? "Unknown"
label.font = .boldSystemFont(ofSize: 16)
return label
})
// Custom subtitle view for messages
searchVC.set(subtitleViewForMessage: { message in
let label = UILabel()
if let textMessage = message as? TextMessage {
label.text = textMessage.text
} else {
label.text = message.type
}
label.textColor = .secondaryLabel
return label
})
// Custom trailing view for messages
searchVC.set(trailingViewForMessage: { message in
let label = UILabel()
let date = Date(timeIntervalSince1970: TimeInterval(message.sentAt))
let formatter = DateFormatter()
formatter.dateFormat = "HH:mm"
label.text = formatter.string(from: date)
label.font = .systemFont(ofSize: 12)
label.textColor = .tertiaryLabel
return label
})
```
#### Initial View
Customize the view displayed before the user enters a search query using the `initialView` property.
```swift lines theme={null}
import CometChatUIKitSwift
let searchVC = CometChatSearch()
// Create a custom initial view
let initialView = UIView()
let imageView = UIImageView(image: UIImage(systemName: "magnifyingglass"))
imageView.tintColor = .systemGray
imageView.contentMode = .scaleAspectFit
imageView.translatesAutoresizingMaskIntoConstraints = false
let label = UILabel()
label.text = "Search for conversations and messages"
label.textColor = .secondaryLabel
label.textAlignment = .center
label.translatesAutoresizingMaskIntoConstraints = false
initialView.addSubview(imageView)
initialView.addSubview(label)
NSLayoutConstraint.activate([
imageView.centerXAnchor.constraint(equalTo: initialView.centerXAnchor),
imageView.centerYAnchor.constraint(equalTo: initialView.centerYAnchor, constant: -20),
imageView.widthAnchor.constraint(equalToConstant: 60),
imageView.heightAnchor.constraint(equalToConstant: 60),
label.topAnchor.constraint(equalTo: imageView.bottomAnchor, constant: 16),
label.leadingAnchor.constraint(equalTo: initialView.leadingAnchor, constant: 20),
label.trailingAnchor.constraint(equalTo: initialView.trailingAnchor, constant: -20)
])
searchVC.set(initialView: initialView)
```
***
#### Mention Configuration
Configure how @all mentions appear in search results using the `setMentionAllLabel` method.
```swift lines theme={null}
import CometChatUIKitSwift
let searchVC = CometChatSearch()
// Set a custom label for @all mentions
searchVC.setMentionAllLabel("all", "Everyone")
```
***
#### DateTime Formatters
By providing a custom implementation of the DateTimeFormatterCallback, you can configure how time and date values are displayed. This ensures consistent formatting for labels such as "Today", "Yesterday", "X minutes ago", and more.
```swift lines theme={null}
import CometChatUIKitSwift
let searchVC = CometChatSearch()
searchVC.dateTimeFormatter.today = { timestamp in
return "Today • \(formattedTime(timestamp))"
}
searchVC.dateTimeFormatter.otherDay = { timestamp in
let df = DateFormatter()
df.dateFormat = "dd MMM yyyy"
return df.string(from: Date(timeIntervalSince1970: timestamp))
}
```
***
#### Text Formatters
The `setTextFormatters` method enables developers to define and apply text formatters that dynamically modify or transform message content before rendering it in the UI. Text formatters can be used for:
* Automatically converting URLs into clickable links
* Applying Markdown or rich text styling
* Replacing certain words or patterns with emojis or predefined text
* Censoring specific words for moderation
By utilizing this method, developers can enhance readability, usability, and compliance with content guidelines. See the [MentionsFormatter Guide](/ui-kit/ios/mentions-formatter-guide) for more details.
***
## Common Patterns
### Present Search from Conversations
Open the search screen from a conversations list:
```swift lines theme={null}
@objc func openSearch() {
let searchVC = CometChatSearch()
searchVC.onConversationClicked = { [weak self] conversation, indexPath in
// Navigate to messages for the selected conversation
let messagesVC = CometChatMessages()
if let user = conversation.conversationWith as? User {
messagesVC.user = user
} else if let group = conversation.conversationWith as? Group {
messagesVC.group = group
}
self?.navigationController?.pushViewController(messagesVC, animated: true)
}
searchVC.onMessageClicked = { [weak self] message in
// Navigate to the message in context
let messagesVC = CometChatMessages()
if let user = message.sender {
messagesVC.user = user
}
self?.navigationController?.pushViewController(messagesVC, animated: true)
}
navigationController?.pushViewController(searchVC, animated: true)
}
```
### Search Within a Specific Conversation
Limit search to messages within a specific user or group chat:
```swift lines theme={null}
// Search within a specific user's conversation
let searchVC = CometChatSearch()
searchVC.user = user
searchVC.set(searchIn: [.messages]) // Only search messages, not conversations
// Or search within a group
let groupSearchVC = CometChatSearch()
groupSearchVC.group = group
groupSearchVC.set(searchIn: [.messages])
```
### Filter Search by Media Type
Show only photo or video messages in search results:
```swift lines theme={null}
let searchVC = CometChatSearch()
// Set available filters with photos as the initial selection
searchVC.set(searchFilters: [.photos, .videos, .documents, .audio], initialFilter: .photos)
// Or programmatically filter messages
let msgBuilder = MessagesRequest.MessageRequestBuilder()
.set(categories: ["message"])
.set(types: ["image", "video"])
searchVC.set(messagesRequestBuilder: msgBuilder)
```
### Custom Search Result Actions
Handle search result selection with custom actions:
```swift lines theme={null}
let searchVC = CometChatSearch()
searchVC.onMessageClicked = { [weak self] message in
// Show action sheet for the selected message
let alert = UIAlertController(title: nil, message: nil, preferredStyle: .actionSheet)
alert.addAction(UIAlertAction(title: "Go to Message", style: .default) { _ in
self?.navigateToMessage(message)
})
alert.addAction(UIAlertAction(title: "Reply", style: .default) { _ in
self?.replyToMessage(message)
})
alert.addAction(UIAlertAction(title: "Forward", style: .default) { _ in
self?.forwardMessage(message)
})
alert.addAction(UIAlertAction(title: "Cancel", style: .cancel))
self?.present(alert, animated: true)
}
```
***
## Related Components
Display conversation list
Display chat messages
Display user list