> ## 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

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

<Accordion title="AI Agent Component Spec">
  ```json theme={null}
  {
    "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"
      }
    }
  }
  ```
</Accordion>

## 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.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/9bgr-iIAUJixmNKk/images/search_overview_flutter.png?fit=max&auto=format&n=9bgr-iIAUJixmNKk&q=85&s=4b5634961b9110176eac80b65920bdc4" width="2560" height="1670" data-path="images/search_overview_flutter.png" />
</Frame>

## Minimal Render

The simplest way to render CometChatSearch:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    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())
    );
    ```
  </Tab>
</Tabs>

You can also embed it as a widget:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    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(),
          ),
        );
      }
    }
    ```
  </Tab>
</Tabs>

## Filtering

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

### ConversationsRequestBuilder

Filter conversations in the search results:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatSearch(
      conversationsRequestBuilder: ConversationsRequestBuilder()
        ..limit = 30,
    )
    ```
  </Tab>
</Tabs>

### MessagesRequestBuilder

Filter messages in the search results:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatSearch(
      messagesRequestBuilder: MessagesRequestBuilder()
        ..limit = 50,
    )
    ```
  </Tab>
</Tabs>

### Scoped Search

Search within a specific user or group conversation:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    // Search within a specific user's conversation
    CometChatSearch(
      user: user,
    )

    // Search within a specific group's conversation
    CometChatSearch(
      group: group,
    )
    ```
  </Tab>
</Tabs>

## 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                       |

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    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');
      },
    )
    ```
  </Tab>
</Tabs>

### 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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    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,
                  ),
                ),
              ),
            ],
          ),
        );
      },
    )
    ```
  </Tab>
</Tabs>

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/9bgr-iIAUJixmNKk/images/search_text_item.png?fit=max&auto=format&n=9bgr-iIAUJixmNKk&q=85&s=989bded7a5e2fcedc2c6fed021c23a2e" width="2560" height="1670" data-path="images/search_text_item.png" />
</Frame>

### Icon Customization

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

## Styling

Customize the appearance of CometChatSearch using `CometChatSearchStyle`.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/9bgr-iIAUJixmNKk/images/search_style_flutter.png?fit=max&auto=format&n=9bgr-iIAUJixmNKk&q=85&s=7542031dcc9e8355a0173dfa2b4031b8" width="2560" height="1670" data-path="images/search_style_flutter.png" />
</Frame>

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    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,
      ),
    )
    ```
  </Tab>
</Tabs>

### 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              |

<CardGroup cols={2}>
  <Card title="Conversations" icon="comments" href="/ui-kit/flutter/v5/conversations">
    Display and manage chat conversations
  </Card>

  <Card title="Message List" icon="list" href="/ui-kit/flutter/v5/message-list">
    Display messages in a conversation
  </Card>

  <Card title="Theming" icon="palette" href="/ui-kit/flutter/v5/theme-introduction">
    Learn how to customize the look and feel
  </Card>

  <Card title="Localization" icon="globe" href="/ui-kit/flutter/v5/localize">
    Support multiple languages in your app
  </Card>
</CardGroup>