Search

A powerful search interface for finding conversations and messages in real time

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