Search Messages

Add full-text message search across conversations with result routing in CometChat Flutter UI Kit.

AI Agent Component Spec

Field	Value
Package	cometchat_chat_uikit
Key components	CometChatSearch, CometChatMessageList, CometChatMessageComposer, CometChatMessageHeader
Init	CometChatUIKit.init(uiKitSettings: uiKitSettings) then CometChatUIKit.login("UID")
Purpose	Full-text message search across conversations with result routing and navigation
Sample app	GitHub
Related	All Guides

Search Messages lets users locate specific messages across conversations and groups using keyword search, then navigate directly to the result.

Before starting, complete the Getting Started guide.

---

Components

Component / Class	Role
CometChatSearch	Main container for searching messages and conversations
CometChatMessageList	Displays messages and supports scrolling to specific messages
CometChatMessageComposer	Supports navigation after selecting a search result
CometChatMessageHeader	Displays search context and navigation controls

---

Integration Steps

1. Launch Search Component

Launch the CometChatSearch widget directly using Navigator or embed it in your widget tree.

Navigator.push(
  context, 
  MaterialPageRoute(builder: (context) => CometChatSearch())
);

---

2. Handle Search Result Clicks

Wire up the onMessageClicked callback to navigate to the message in context.

CometChatSearch(
  onMessageClicked: (message) {
    // Navigate to the conversation containing this message
    Navigator.push(
      context,
      MaterialPageRoute(
        builder: (context) => CometChatMessageList(
          user: message.sender, // or group for group messages
        ),
      ),
    );
  },
  onConversationClicked: (conversation) {
    // Navigate to the selected conversation
    if (conversation.conversationWith is User) {
      Navigator.push(
        context,
        MaterialPageRoute(
          builder: (context) => CometChatMessageList(
            user: conversation.conversationWith as User,
          ),
        ),
      );
    } else if (conversation.conversationWith is Group) {
      Navigator.push(
        context,
        MaterialPageRoute(
          builder: (context) => CometChatMessageList(
            group: conversation.conversationWith as Group,
          ),
        ),
      );
    }
  },
);

---

3. Filter Search Results

Use request builders to customize what gets searched.

CometChatSearch(
  // Filter conversations
  conversationsRequestBuilder: ConversationsRequestBuilder()
    ..limit = 30,
  // Filter messages
  messagesRequestBuilder: MessagesRequestBuilder()
    ..limit = 50
    ..searchKeyword = "hello",
);

---

4. Customize Search Appearance

Apply custom styling to match your app’s design.

CometChatSearch(
  searchStyle: CometChatSearchStyle(
    backgroundColor: Colors.white,
    searchTextStyle: TextStyle(fontSize: 16),
    searchFilterChipTextStyle: TextStyle(color: Colors.blue),
    searchMessageItemBackgroundColor: Color(0xFFF5F5F5),
  ),
);

---

Feature Matrix

Feature	Component / Method	Description
Search input	CometChatSearch	Main search interface
Display results	CometChatSearch	Shows matching conversations and messages
Conversation click	onConversationClicked	Handle conversation selection
Message click	onMessageClicked	Handle message selection
Filter conversations	conversationsRequestBuilder	Customize conversation search
Filter messages	messagesRequestBuilder	Customize message search

---

Complete Example

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

class SearchScreen extends StatelessWidget {
  const SearchScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Search')),
      body: CometChatSearch(
        onConversationClicked: (conversation) {
          _navigateToConversation(context, conversation);
        },
        onMessageClicked: (message) {
          _navigateToMessage(context, message);
        },
        onBack: () {
          Navigator.pop(context);
        },
        onError: (error) {
          ScaffoldMessenger.of(context).showSnackBar(
            SnackBar(content: Text('Error: ${error.message}')),
          );
        },
      ),
    );
  }

  void _navigateToConversation(BuildContext context, Conversation conversation) {
    if (conversation.conversationWith is User) {
      Navigator.push(
        context,
        MaterialPageRoute(
          builder: (context) => CometChatMessageList(
            user: conversation.conversationWith as User,
          ),
        ),
      );
    } else if (conversation.conversationWith is Group) {
      Navigator.push(
        context,
        MaterialPageRoute(
          builder: (context) => CometChatMessageList(
            group: conversation.conversationWith as Group,
          ),
        ),
      );
    }
  }

  void _navigateToMessage(BuildContext context, BaseMessage message) {
    // Navigate to the message's conversation
    // Implementation depends on your app's navigation structure
  }
}

---

Next Steps

Search Component

Full search component reference.

Message List

Render real-time message threads.

All Guides

Browse all feature and formatter guides.

Sample App

Full working sample application on GitHub.