> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-agent-native-development.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Search

> Add CometChat Flutter UI Kit search for conversations and messages with categorized results and navigation callbacks.

<Accordion title="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](#actions-and-events) |
  | View slots | `loadingStateView` · `emptyStateView` · `errorStateView` · `initialStateView` · `conversationItemView` · `conversationTitleView` · `conversationLeadingView` · `conversationSubtitleView` · +6 more — [details](#custom-view-slots) |
  | 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](#functionality) |
</Accordion>

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

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-agent-native-development/Y7tnXGnxeD6Z3sW-/images/search_overview_flutter.png?fit=max&auto=format&n=Y7tnXGnxeD6Z3sW-&q=85&s=c4238001f5bda784bda86bfbdafa5617" width="2560" height="1670" data-path="images/search_overview_flutter.png" />
</Frame>

***

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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatSearch(
      onConversationClicked: (conversation) {
        // Navigate to conversation
      },
      onMessageClicked: (message) {
        // Navigate to message in context
      },
    )
    ```
  </Tab>
</Tabs>

***

## Quick Start

Using Navigator:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    Navigator.push(context, MaterialPageRoute(builder: (context) => CometChatSearch()));
    ```
  </Tab>
</Tabs>

Embedding as a widget:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    @override
    Widget build(BuildContext context) {
      return Scaffold(
        body: SafeArea(
          child: CometChatSearch(),
        ),
      );
    }
    ```
  </Tab>
</Tabs>

Launching from conversations with search button:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatConversations(
      hideSearch: false,
      searchReadOnly: true,
      onSearchTap: () {
        Navigator.push(context, MaterialPageRoute(
          builder: (context) => CometChatSearch(
            onConversationClicked: (conversation) {
              // Navigate to chat
            },
            onMessageClicked: (message) {
              // Navigate to message
            },
          ),
        ));
      },
    )
    ```
  </Tab>
</Tabs>

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.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatSearch(
      onConversationClicked: (conversation) {
        final entity = conversation.conversationWith;
        if (entity is User) {
          navigateToUserChat(entity);
        } else if (entity is Group) {
          navigateToGroupChat(entity);
        }
      },
    )
    ```
  </Tab>
</Tabs>

#### `onMessageClicked`

Fires when a message result is tapped.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatSearch(
      onMessageClicked: (message) {
        // Navigate to the message in its conversation
      },
    )
    ```
  </Tab>
</Tabs>

#### `onBack`

Fires when the user presses the back button.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatSearch(
      onBack: () {
        Navigator.pop(context);
      },
    )
    ```
  </Tab>
</Tabs>

#### `onError`

Fires on internal errors.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatSearch(
      onError: (e) {
        debugPrint("Search error: $e");
      },
    )
    ```
  </Tab>
</Tabs>

***

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

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

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

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

### State Views

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatSearch(
      emptyStateView: (context) => Center(child: Text("No results found")),
      errorStateView: (context) => Center(child: Text("Search failed")),
      loadingStateView: (context) => Center(child: CircularProgressIndicator()),
    )
    ```
  </Tab>
</Tabs>

***

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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatSearch(
      searchStyle: CometChatSearchStyle(
        backgroundColor: Colors.white,
        searchBackgroundColor: Color(0xFFF5F5F5),
        searchBorderRadius: BorderRadius.circular(12),
      ),
    )
    ```
  </Tab>
</Tabs>

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-agent-native-development/Y7tnXGnxeD6Z3sW-/images/search_style_flutter.png?fit=max&auto=format&n=Y7tnXGnxeD6Z3sW-&q=85&s=484592a868eeb667d9aae0cffc42d73b" width="2560" height="1670" data-path="images/search_style_flutter.png" />
</Frame>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Conversations" icon="comments" href="/ui-kit/flutter/conversations">
    Browse recent conversations
  </Card>

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

  <Card title="Component Styling" icon="paintbrush" href="/ui-kit/flutter/component-styling">
    Detailed styling reference
  </Card>

  <Card title="Users" icon="user" href="/ui-kit/flutter/users">
    Browse available users
  </Card>
</CardGroup>


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