Search - CometChat Docs

AI Integration Quick Reference

Field	Value
Component	`CometChatSearch`
Package	`cometchat_chat_uikit`
Import	`import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';`
Purpose	Add CometChat Flutter UI Kit search for conversations and messages with categorized results and navigation callbacks.
Data props	`user` · `group` · `conversationsRequestBuilder` · `messagesRequestBuilder`
Actions	`onBack` · `onConversationClicked` · `onMessageClicked` · `onEmpty` · `onError` · `onMessagesLoad` · `onConversationsLoad` — details
View slots	`loadingStateView` · `emptyStateView` · `errorStateView` · `initialStateView` · `conversationItemView` · `conversationTitleView` · `conversationLeadingView` · `conversationSubtitleView` · +6 more — details
Styling	`searchStyle` — the app `ThemeData` does not reach inside a kit widget, so scope colours here.
Layout	Fills its parent — place it in an `Expanded` (or a sized box) inside a `Column`, or layout throws an unbounded-height error at render.
Prerequisites	`CometChatUIKit` initialised and a user logged in.
Full props	35 props

CometChatSearch provides unified search functionality across conversations and messages. In V6, it uses a single consolidated SearchBloc replacing the three separate controllers from V5.

Where It Fits

CometChatSearch is typically launched from a search button in the conversations list or message header. It searches across both conversations and messages, displaying results in categorized sections.

Dart

CometChatSearch(
  onConversationClicked: (conversation) {
    // Navigate to conversation
  },
  onMessageClicked: (message) {
    // Navigate to message in context
  },
)

Quick Start

Using Navigator:

Dart

Navigator.push(context, MaterialPageRoute(builder: (context) => CometChatSearch()));

Embedding as a widget:

Dart

@override
Widget build(BuildContext context) {
  return Scaffold(
    body: SafeArea(
      child: CometChatSearch(),
    ),
  );
}

Launching from conversations with search button:

Dart

CometChatConversations(
  hideSearch: false,
  searchReadOnly: true,
  onSearchTap: () {
    Navigator.push(context, MaterialPageRoute(
      builder: (context) => CometChatSearch(
        onConversationClicked: (conversation) {
          // Navigate to chat
        },
        onMessageClicked: (message) {
          // Navigate to message
        },
      ),
    ));
  },
)

Prerequisites: CometChat SDK initialized with CometChatUIKit.init() and a user logged in.

Actions and Events

Callback Methods

`onConversationClicked`

Fires when a conversation result is tapped.

Dart

CometChatSearch(
  onConversationClicked: (conversation) {
    final entity = conversation.conversationWith;
    if (entity is User) {
      navigateToUserChat(entity);
    } else if (entity is Group) {
      navigateToGroupChat(entity);
    }
  },
)

`onMessageClicked`

Fires when a message result is tapped.

Dart

CometChatSearch(
  onMessageClicked: (message) {
    // Navigate to the message in its conversation
  },
)

`onBack`

Fires when the user presses the back button.

Dart

CometChatSearch(
  onBack: () {
    Navigator.pop(context);
  },
)

`onError`

Fires on internal errors.

Dart

CometChatSearch(
  onError: (e) {
    debugPrint("Search error: $e");
  },
)

Functionality

Property	Type	Default	Description
`onBack`	`VoidCallback?`	`null`	`onBack` callback triggered on closing a screen
`onConversationClicked`	`Function(Conversation conversation)?`	`null`	Called when a conversation result is tapped.
`onMessageClicked`	`Function(BaseMessage message)?`	`null`	Called when a message result is tapped.
`onEmpty`	`OnEmpty?`	`null`	`onEmpty` callback triggered when the list is empty
`onError`	`OnError?`	`null`	`onError` callback triggered in case any error happens when fetching data
`onMessagesLoad`	`OnLoad<BaseMessage>?`	`null`	Called once message results have loaded.
`onConversationsLoad`	`OnLoad<Conversation>?`	`null`	Called once conversation results have loaded.
`searchFilters`	`List<SearchFilter>?`	`null`	Filters offered above the results, such as photos or links.
`searchIn`	`List<SearchScope>?`	`null`	Scopes the search — conversations, messages, or both.
`user`	`User?`	`null`	Target user for 1-on-1 conversation (mutually exclusive with `group`)
`group`	`Group?`	`null`	Target group for group conversation (mutually exclusive with `user`)
`searchStyle`	`CometChatSearchStyle?`	`null`	Style object for this widget. The app `ThemeData` does not reach inside a kit widget, so scope colours here.
`searchBackIcon`	`Widget?`	`null`	Icon for the back affordance in the search bar.
`searchClearIcon`	`Widget?`	`null`	Icon for the clear affordance in the search bar.
`loadingStateView`	`WidgetBuilder?`	`null`	`loadingStateView` is a parameter used to show the loading state view in case of loading
`emptyStateView`	`WidgetBuilder?`	`null`	`emptyStateView` returns view fow empty state
`errorStateView`	`WidgetBuilder?`	`null`	`errorStateView` is a parameter used to show the error state view in case of any error
`initialStateView`	`WidgetBuilder?`	`null`	View shown before a query is entered.
`conversationItemView`	`Widget? Function(BuildContext, Conversation)?`	`null`	Replaces an entire conversation result row.
`conversationTitleView`	`Widget? Function(BuildContext, Conversation)?`	`null`	Replaces the title slot of a conversation result row.
`conversationLeadingView`	`Widget? Function(BuildContext, Conversation)?`	`null`	Replaces the leading slot of a conversation result row.
`conversationSubtitleView`	`Widget? Function(BuildContext, Conversation)?`	`null`	Replaces the subtitle slot of a conversation result row.
`conversationTailView`	`Widget? Function(BuildContext, Conversation)?`	`null`	Replaces the trailing slot of a conversation result row.
`usersStatusVisibility`	`bool?`	`null`	`usersStatusVisibility` controls visibility of status indicator shown if a user is online
`receiptsVisibility`	`bool?`	`null`	`receiptsVisibility` controls visibility of receipts
`groupTypeVisibility`	`bool?`	`null`	`groupTypeVisibility` Hide the group type icon which is visible on the group icon.
`dateSeparatorFormatterCallback`	`DateTimeFormatterCallback?`	`null`	Builds the date string shown on the separator between result groups.
`timeSeparatorFormatterCallback`	`DateTimeFormatterCallback?`	`null`	Builds the time string shown on a result row.
`searchTextMessageView`	`Widget? Function(BuildContext, TextMessage)?`	`null`	Replaces the row used for a text-message result.
`searchImageMessageView`	`Widget? Function(BuildContext, MediaMessage)?`	`null`	Replaces the row used for an image-message result.
`searchVideoMessageView`	`Widget? Function(BuildContext, MediaMessage)?`	`null`	Replaces the row used for a video-message result.
`searchFileMessageView`	`Widget? Function(BuildContext, MediaMessage)?`	`null`	Replaces the row used for a file-message result.
`searchAudioMessageView`	`Widget? Function(BuildContext, MediaMessage)?`	`null`	Replaces the row used for an audio-message result.
`conversationsRequestBuilder`	`ConversationsRequestBuilder?`	`null`	`conversationsRequestBuilder` Request builder to fetch conversations.
`messagesRequestBuilder`	`MessagesRequestBuilder?`	`null`	Request builder used to fetch message results.

Custom View Slots

Conversation Item View

Replace the conversation result item.

Dart

CometChatSearch(
  conversationItemView: (context, conversation) {
    final entity = conversation.conversationWith;
    final name = entity is User ? entity.name : (entity is Group ? entity.name : "");
    return ListTile(
      leading: CircleAvatar(child: Text(name.isNotEmpty ? name[0] : "")),
      title: Text(name),
    );
  },
)

Message Item View

Replace a message result item. There is no single messageItemView — message results are overridden per message type: searchTextMessageView, searchImageMessageView, searchVideoMessageView, searchFileMessageView, and searchAudioMessageView. Each receives (BuildContext, message).

Dart

CometChatSearch(
  searchTextMessageView: (context, message) {
    return ListTile(
      title: Text(message.sender?.name ?? ""),
      subtitle: Text(message.text),
    );
  },
  searchImageMessageView: (context, message) {
    return ListTile(
      title: Text(message.sender?.name ?? ""),
      subtitle: const Text("Image"),
    );
  },
)

State Views

Dart

CometChatSearch(
  emptyStateView: (context) => Center(child: Text("No results found")),
  errorStateView: (context) => Center(child: Text("Search failed")),
  loadingStateView: (context) => Center(child: CircularProgressIndicator()),
)

Advanced

BLoC Access

The search widget uses SearchBloc internally:

Component	Description
`SearchBloc`	Single consolidated BLoC for all search types
`SearchEvent`	Events: `SearchTextChanged`, `ClearSearch`, `LoadMoreConversationResults`, `LoadMoreMessageResults`
`SearchState`	Search state with conversation and message results

V5 → V6 Migration

V5	V6
`CometChatSearchController`	`SearchBloc`
`CometChatConversationsSearchController`	Merged into `SearchBloc`
`CometChatMessagesSearchController`	Merged into `SearchBloc`
`SearchUtils`	Inlined into `SearchBloc`
3 separate controllers	1 unified BLoC

Style

Dart

CometChatSearch(
  searchStyle: CometChatSearchStyle(
    backgroundColor: Colors.white,
    searchBackgroundColor: Color(0xFFF5F5F5),
    searchBorderRadius: BorderRadius.circular(12),
  ),
)

Next Steps

Conversations

Browse recent conversations

Message List

Display messages in a conversation

Component Styling

Detailed styling reference

Users

Browse available users

​Where It Fits

​Quick Start

​Actions and Events

​Callback Methods

​onConversationClicked

​onMessageClicked

​onBack

​onError

​Functionality

​Custom View Slots

​Conversation Item View

​Message Item View

​State Views

​Advanced

​BLoC Access

​V5 → V6 Migration

​Style

​Next Steps