Search - CometChat Docs

AI Agent Component Spec

{
  "component": "CometChatSearch",
  "package": "cometchat_chat_uikit",
  "import": "import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';",
  "description": "A powerful search interface that allows users to search across conversations and messages in real time with filters and customization options",
  "primaryOutput": {
    "prop": "onMessageClicked",
    "type": "void Function(BaseMessage message)"
  },
  "props": {
    "data": {
      "user": {
        "type": "User?",
        "default": "null",
        "note": "User object for user message search"
      },
      "group": {
        "type": "Group?",
        "default": "null",
        "note": "Group object for group message search"
      },
      "searchFilters": {
        "type": "List<SearchFilter>?",
        "default": "null",
        "note": "List of filters to be shown in the search screen"
      },
      "searchIn": {
        "type": "List<SearchScope>?",
        "default": "null",
        "note": "List of scopes to be shown in the search result"
      }
    },
    "callbacks": {
      "onBack": "VoidCallback?",
      "onConversationClicked": "void Function(Conversation conversation)?",
      "onMessageClicked": "void Function(BaseMessage message)?",
      "onError": "OnError?",
      "onConversationsLoad": "OnLoad<Conversation>?",
      "onMessagesLoad": "OnLoad<BaseMessage>?",
      "onEmpty": "OnEmpty?"
    },
    "visibility": {
      "usersStatusVisibility": {
        "type": "bool?",
        "default": "null"
      },
      "receiptsVisibility": {
        "type": "bool?",
        "default": "null"
      },
      "groupTypeVisibility": {
        "type": "bool?",
        "default": "null"
      }
    },
    "viewSlots": {
      "loadingStateView": "WidgetBuilder?",
      "errorStateView": "WidgetBuilder?",
      "emptyStateView": "WidgetBuilder?",
      "initialStateView": "WidgetBuilder?",
      "conversationItemView": "Widget? Function(BuildContext, Conversation)?",
      "conversationTitleView": "Widget? Function(BuildContext, Conversation)?",
      "conversationLeadingView": "Widget? Function(BuildContext, Conversation)?",
      "conversationSubtitleView": "Widget? Function(BuildContext, Conversation)?",
      "conversationTailView": "Widget? Function(BuildContext, Conversation)?",
      "searchTextMessageView": "Widget? Function(BuildContext, TextMessage)?",
      "searchImageMessageView": "Widget? Function(BuildContext, MediaMessage)?",
      "searchVideoMessageView": "Widget? Function(BuildContext, MediaMessage)?",
      "searchFileMessageView": "Widget? Function(BuildContext, MediaMessage)?",
      "searchAudioMessageView": "Widget? Function(BuildContext, MediaMessage)?",
      "searchMessageLinkView": "Widget? Function(BuildContext, BaseMessage)?"
    },
    "formatting": {
      "dateSeparatorFormatterCallback": {
        "type": "DateTimeFormatterCallback?",
        "default": "null"
      },
      "timeSeparatorFormatterCallback": {
        "type": "DateTimeFormatterCallback?",
        "default": "null"
      }
    }
  },
  "events": [],
  "sdkListeners": [],
  "compositionExample": {
    "description": "CometChatSearch can be used standalone or embedded within other screens",
    "components": ["CometChatConversations", "CometChatMessageList"],
    "flow": "User searches → Results displayed → User clicks result → Navigate to conversation/message"
  },
  "types": {
    "SearchFilter": {
      "label": "String",
      "icon": "Widget?"
    },
    "SearchScope": {
      "conversations": "bool",
      "messages": "bool"
    }
  }
}

Where It Fits

CometChatSearch is a full-screen search experience that allows users to find messages, conversations, media, and more through an intuitive and filterable search interface. It can be embedded in multiple contexts — as part of the conversation list, message header, or as a standalone full-screen search experience.

Minimal Render

The simplest way to render CometChatSearch:

Dart

import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
import 'package:flutter/material.dart';

// Using Navigator to launch CometChatSearch
Navigator.push(
  context, 
  MaterialPageRoute(builder: (context) => CometChatSearch())
);

You can also embed it as a widget:

Dart

import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
import 'package:flutter/material.dart';

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

Filtering

Use the request builder props to filter which items appear in the search results.

ConversationsRequestBuilder

Filter conversations in the search results:

Dart

CometChatSearch(
  conversationsRequestBuilder: ConversationsRequestBuilder()
    ..limit = 30,
)

MessagesRequestBuilder

Filter messages in the search results:

Dart

CometChatSearch(
  messagesRequestBuilder: MessagesRequestBuilder()
    ..limit = 50,
)

Scoped Search

Search within a specific user or group conversation:

Dart

// Search within a specific user's conversation
CometChatSearch(
  user: user,
)

// Search within a specific group's conversation
CometChatSearch(
  group: group,
)

Actions and Events

Callback Props

Component-level callbacks that fire on specific user interactions:

Callback	Signature	Fires When
`onConversationClicked`	`void Function(Conversation conversation)?`	User clicks a conversation from search results
`onMessageClicked`	`void Function(BaseMessage message)?`	User clicks a message from search results
`onBack`	`VoidCallback?`	User clicks the back button
`onError`	`OnError?`	An error occurs in the component
`onConversationsLoad`	`OnLoad<Conversation>?`	Conversations are loaded
`onMessagesLoad`	`OnLoad<BaseMessage>?`	Messages are loaded
`onEmpty`	`OnEmpty?`	Search results are empty

Dart

CometChatSearch(
  onConversationClicked: (conversation) {
    // Navigate to the conversation
    print('Conversation clicked: ${conversation.conversationId}');
  },
  onMessageClicked: (message) {
    // Navigate to the message
    print('Message clicked: ${message.id}');
  },
  onBack: () {
    Navigator.pop(context);
  },
  onError: (e) {
    print('Error: $e');
  },
)

Global UI Events

The CometChatSearch component does not produce any global UI events.

Custom View Slots

Customize the appearance of CometChatSearch by replacing default views with your own widgets.

State Views

Slot	Signature	Replaces
`loadingStateView`	`WidgetBuilder?`	Loading spinner
`emptyStateView`	`WidgetBuilder?`	Empty state display
`errorStateView`	`WidgetBuilder?`	Error state display
`initialStateView`	`WidgetBuilder?`	Initial state before search

Conversation View Slots

Slot	Signature	Replaces
`conversationItemView`	`Widget? Function(BuildContext, Conversation)?`	Entire conversation list item
`conversationLeadingView`	`Widget? Function(BuildContext, Conversation)?`	Avatar / left section
`conversationTitleView`	`Widget? Function(BuildContext, Conversation)?`	Name / title text
`conversationSubtitleView`	`Widget? Function(BuildContext, Conversation)?`	Secondary text / preview
`conversationTailView`	`Widget? Function(BuildContext, Conversation)?`	Right section / timestamp

Message View Slots

Slot	Signature	Replaces
`searchTextMessageView`	`Widget? Function(BuildContext, TextMessage)?`	Text message item
`searchImageMessageView`	`Widget? Function(BuildContext, MediaMessage)?`	Image message item
`searchVideoMessageView`	`Widget? Function(BuildContext, MediaMessage)?`	Video message item
`searchFileMessageView`	`Widget? Function(BuildContext, MediaMessage)?`	File message item
`searchAudioMessageView`	`Widget? Function(BuildContext, MediaMessage)?`	Audio message item
`searchMessageLinkView`	`Widget? Function(BuildContext, BaseMessage)?`	Link message item

Example: Custom Text Message View

Dart

CometChatSearch(
  searchTextMessageView: (context, message) {
    String senderName = message.sender?.name ?? "Unknown";
    return Container(
      padding: const EdgeInsets.all(16),
      width: double.infinity,
      color: const Color(0xFFE8E4F3),
      child: Row(
        children: [
          Text(
            "$senderName: ",
            style: const TextStyle(
              color: Color(0xFF6B4FBB),
              fontSize: 16,
              fontWeight: FontWeight.bold,
            ),
          ),
          Expanded(
            child: Text(
              message.text,
              maxLines: 1,
              overflow: TextOverflow.ellipsis,
              style: const TextStyle(
                color: Color(0xFF4A4A4A),
                fontSize: 16,
              ),
            ),
          ),
        ],
      ),
    );
  },
)

Icon Customization

Prop	Type	Description
`searchBackIcon`	`Widget?`	Custom back icon
`searchClearIcon`	`Widget?`	Custom clear icon

Styling

Customize the appearance of CometChatSearch using CometChatSearchStyle.

Dart

CometChatSearch(
  searchStyle: CometChatSearchStyle(
    backgroundColor: const Color(0xFFEDEAFA),
    searchBackgroundColor: Colors.white,
    searchTextColor: Colors.black,
    searchPlaceHolderTextColor: Colors.grey,
    
    // Filter chip styling
    searchFilterChipBackgroundColor: Colors.grey[200],
    searchFilterChipSelectedBackgroundColor: Colors.purple,
    searchFilterChipTextColor: Colors.black,
    searchFilterChipSelectedTextColor: Colors.white,
    
    // Conversation item styling
    searchConversationItemBackgroundColor: const Color(0xFFEDEAFA),
    searchConversationTitleTextStyle: const TextStyle(fontWeight: FontWeight.bold),
    searchConversationSubTitleTextStyle: const TextStyle(color: Colors.grey),
    
    // Message item styling
    searchMessageItemBackgroundColor: const Color(0xFFEDEAFA),
    searchMessageTitleTextStyle: const TextStyle(fontWeight: FontWeight.bold),
    
    // See more button
    searchSeeMoreColor: Colors.purple,
  ),
)

Style Properties

Property	Type	Description
`backgroundColor`	`Color?`	Background color of the search component
`searchBackgroundColor`	`Color?`	Background color of the search text field
`searchBorder`	`BorderSide?`	Border of the search text field
`searchBorderRadius`	`BorderRadius?`	Border radius of the search text field
`searchTextColor`	`Color?`	Color of the search text
`searchTextStyle`	`TextStyle?`	Style of the search text
`searchPlaceHolderTextColor`	`Color?`	Color of the placeholder text
`searchPlaceHolderTextStyle`	`TextStyle?`	Style of the placeholder text
`searchBackIconColor`	`Color?`	Color of the back icon
`searchClearIconColor`	`Color?`	Color of the clear icon
`searchFilterChipBackgroundColor`	`Color?`	Background color of filter chips
`searchFilterChipSelectedBackgroundColor`	`Color?`	Background color of selected filter chips
`searchFilterChipTextColor`	`Color?`	Text color of filter chips
`searchFilterChipTextStyle`	`TextStyle?`	Text style of filter chips
`searchFilterChipSelectedTextColor`	`Color?`	Text color of selected filter chips
`searchFilterChipSelectedTextStyle`	`TextStyle?`	Text style of selected filter chips
`searchFilterIconColor`	`Color?`	Color of filter icons
`searchFilterSelectedIconColor`	`Color?`	Color of selected filter icons
`searchFilterChipBorder`	`Border?`	Border of filter chips
`searchFilterChipSelectedBorder`	`Border?`	Border of selected filter chips
`searchFilterChipBorderRadius`	`BorderRadius?`	Border radius of filter chips
`searchSectionHeaderTextColor`	`Color?`	Color of section header text
`searchSectionHeaderTextStyle`	`TextStyle?`	Style of section header text
`searchConversationItemBackgroundColor`	`Color?`	Background color of conversation items
`searchConversationTitleTextColor`	`Color?`	Text color of conversation titles
`searchConversationTitleTextStyle`	`TextStyle?`	Style of conversation titles
`searchConversationSubTitleTextStyle`	`TextStyle?`	Style of conversation subtitles
`searchConversationTitleSubTextColor`	`Color?`	Text color of conversation subtitles
`searchConversationDateTextColor`	`Color?`	Text color of conversation dates
`searchConversationDateTextStyle`	`TextStyle?`	Style of conversation dates
`searchMessageItemBackgroundColor`	`Color?`	Background color of message items
`searchMessageTitleTextColor`	`Color?`	Text color of message titles
`searchMessageTitleTextStyle`	`TextStyle?`	Style of message titles
`searchMessageSubTitleTextColor`	`Color?`	Text color of message subtitles
`searchMessageSubTitleTextStyle`	`TextStyle?`	Style of message subtitles
`searchMessageTimeStampStyle`	`CometChatDateStyle?`	Style of message timestamps
`searchMessageDateSeparatorStyle`	`CometChatDateStyle?`	Style of date separators
`searchEmptyStateTextColor`	`Color?`	Text color for empty state
`searchEmptyStateTextStyle`	`TextStyle?`	Style for empty state text
`searchEmptyStateSubtitleColor`	`Color?`	Color for empty state subtitle
`searchEmptyStateSubtitleStyle`	`TextStyle?`	Style for empty state subtitle
`searchErrorStateTextColor`	`Color?`	Text color for error state
`searchErrorStateTextStyle`	`TextStyle?`	Style for error state text
`searchErrorStateSubtitleColor`	`Color?`	Color for error state subtitle
`searchErrorStateSubtitleStyle`	`TextStyle?`	Style for error state subtitle
`searchSeeMoreColor`	`Color?`	Color of “See More” button
`searchSeeMoreStyle`	`TextStyle?`	Style of “See More” button
`avatarStyle`	`CometChatAvatarStyle?`	Style for avatars
`badgeStyle`	`CometChatBadgeStyle?`	Style for badges

Props Reference

Prop	Type	Default	Description
`user`	`User?`	`null`	User object for scoped search
`group`	`Group?`	`null`	Group object for scoped search
`searchFilters`	`List<SearchFilter>?`	`null`	List of filters to show
`searchIn`	`List<SearchScope>?`	`null`	List of search scopes
`usersStatusVisibility`	`bool?`	`null`	Show/hide user status indicator
`receiptsVisibility`	`bool?`	`null`	Show/hide message receipts
`groupTypeVisibility`	`bool?`	`null`	Show/hide group type icon
`onBack`	`VoidCallback?`	`null`	Back button callback
`onConversationClicked`	`Function(Conversation)?`	`null`	Conversation click callback
`onMessageClicked`	`Function(BaseMessage)?`	`null`	Message click callback
`onError`	`OnError?`	`null`	Error callback
`onConversationsLoad`	`OnLoad<Conversation>?`	`null`	Conversations load callback
`onMessagesLoad`	`OnLoad<BaseMessage>?`	`null`	Messages load callback
`onEmpty`	`OnEmpty?`	`null`	Empty state callback
`loadingStateView`	`WidgetBuilder?`	`null`	Custom loading view
`errorStateView`	`WidgetBuilder?`	`null`	Custom error view
`emptyStateView`	`WidgetBuilder?`	`null`	Custom empty view
`initialStateView`	`WidgetBuilder?`	`null`	Custom initial view
`conversationItemView`	`Widget? Function(BuildContext, Conversation)?`	`null`	Custom conversation item
`conversationTitleView`	`Widget? Function(BuildContext, Conversation)?`	`null`	Custom conversation title
`conversationLeadingView`	`Widget? Function(BuildContext, Conversation)?`	`null`	Custom conversation leading view
`conversationSubtitleView`	`Widget? Function(BuildContext, Conversation)?`	`null`	Custom conversation subtitle
`conversationTailView`	`Widget? Function(BuildContext, Conversation)?`	`null`	Custom conversation tail view
`searchTextMessageView`	`Widget? Function(BuildContext, TextMessage)?`	`null`	Custom text message view
`searchImageMessageView`	`Widget? Function(BuildContext, MediaMessage)?`	`null`	Custom image message view
`searchVideoMessageView`	`Widget? Function(BuildContext, MediaMessage)?`	`null`	Custom video message view
`searchFileMessageView`	`Widget? Function(BuildContext, MediaMessage)?`	`null`	Custom file message view
`searchAudioMessageView`	`Widget? Function(BuildContext, MediaMessage)?`	`null`	Custom audio message view
`searchMessageLinkView`	`Widget? Function(BuildContext, BaseMessage)?`	`null`	Custom link message view
`searchBackIcon`	`Widget?`	`null`	Custom back icon
`searchClearIcon`	`Widget?`	`null`	Custom clear icon
`dateSeparatorFormatterCallback`	`DateTimeFormatterCallback?`	`null`	Date separator formatter
`timeSeparatorFormatterCallback`	`DateTimeFormatterCallback?`	`null`	Time separator formatter
`conversationsProtocol`	`ConversationsBuilderProtocol?`	`null`	Conversations builder protocol
`conversationsRequestBuilder`	`ConversationsRequestBuilder?`	`null`	Conversations request builder
`messagesRequestBuilder`	`MessagesRequestBuilder?`	`null`	Messages request builder
`searchStyle`	`CometChatSearchStyle?`	`null`	Style configuration

Conversations

Display and manage chat conversations

Message List

Display messages in a conversation

Theming

Learn how to customize the look and feel

Localization

Support multiple languages in your app

​Where It Fits

​Minimal Render

​Filtering

​ConversationsRequestBuilder

​MessagesRequestBuilder

​Scoped Search

​Actions and Events

​Callback Props

​Global UI Events

​Custom View Slots

​State Views

​Conversation View Slots

​Message View Slots

​Example: Custom Text Message View

​Icon Customization

​Styling

​Style Properties

​Props Reference