> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-llms-scoped-indexes.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-llms-scoped-indexes/i4Q5Nw9DEcclqV3C/images/search_overview_flutter.png?fit=max&auto=format&n=i4Q5Nw9DEcclqV3C&q=85&s=1059bfd94932650eb947d0e837e81400" 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-llms-scoped-indexes/i4Q5Nw9DEcclqV3C/images/search_text_item.png?fit=max&auto=format&n=i4Q5Nw9DEcclqV3C&q=85&s=c1d4596b9bfde1cc5a5c5087f0c62ad7" 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-llms-scoped-indexes/i4Q5Nw9DEcclqV3C/images/search_style_flutter.png?fit=max&auto=format&n=i4Q5Nw9DEcclqV3C&q=85&s=d6494fc44ca085a89f4f66bdc745d7e4" 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>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.