Search - CometChat Docs

AI Agent Component Spec

{
  "component": "CometChatSearch",
  "package": "com.cometchat.chatuikit.search",
  "xmlElement": "<com.cometchat.chatuikit.search.CometChatSearch />",
  "description": "Real-time search interface for finding conversations and messages with filters, scopes, and customization options.",
  "primaryOutput": {
    "conversationClicked": {
      "method": "setOnConversationClicked",
      "type": "OnItemClick<Conversation>"
    },
    "messageClicked": {
      "method": "setOnMessageClicked",
      "type": "OnItemClick<BaseMessage>"
    }
  },
  "methods": {
    "data": {
      "setConversationsRequestBuilder": {
        "type": "ConversationsRequest.ConversationsRequestBuilder",
        "default": "SDK default",
        "note": "Pass the builder, not the result of .build()"
      },
      "setMessagesRequestBuilder": {
        "type": "MessagesRequest.MessagesRequestBuilder",
        "default": "SDK default",
        "note": "Pass the builder, not the result of .build()"
      }
    },
    "callbacks": {
      "setOnConversationClicked": "OnItemClick<Conversation>",
      "setOnMessageClicked": "OnItemClick<BaseMessage>",
      "setOnBackPressListener": "OnBackPress",
      "setOnError": "OnError",
      "setOnEmpty": "OnEmpty",
      "setOnLoadMessages": "OnLoad<BaseMessage>",
      "setOnLoadConversations": "OnLoad<Conversation>"
    },
    "visibility": {
      "setEmptyStateVisibility": { "type": "int (View.VISIBLE | View.GONE)", "default": "View.VISIBLE" },
      "setErrorStateVisibility": { "type": "int", "default": "View.VISIBLE" }
    },
    "functionality": {
      "setUid": { "type": "String", "note": "Scope search to a specific user conversation" },
      "setGuid": { "type": "String", "note": "Scope search to a specific group conversation" },
      "setSearchFilters": { "type": "List<UIKitConstants.SearchFilter>", "note": "Filters rendered as chips" },
      "setInitialSearchFilter": { "type": "UIKitConstants.SearchFilter", "note": "Default active filter on load" },
      "setSearchIn": { "type": "List<SearchScope>", "note": "Entities to search in" },
      "setHideGroupType": { "type": "boolean", "default": "false" },
      "setHideUserStatus": { "type": "boolean", "default": "false" }
    },
    "viewSlots": {
      "setConversationItemView": "ConversationsSearchViewHolderListener — entire conversation item row",
      "setTextMessageItemView": "MessagesSearchViewHolderListener<TextMessage> — text message item",
      "setImageMessageItemView": "MessagesSearchViewHolderListener<MediaMessage> — image message item",
      "setAudioMessageItemView": "MessagesSearchViewHolderListener<MediaMessage> — audio message item",
      "setVideoMessageItemView": "MessagesSearchViewHolderListener<MediaMessage> — video message item",
      "setDocumentMessageItemView": "MessagesSearchViewHolderListener<MediaMessage> — document message item",
      "setLinkMessageItemView": "MessagesSearchViewHolderListener<TextMessage> — link message item",
      "setInitialView": "@LayoutRes int — initial state before search",
      "setEmptyView": "@LayoutRes int — empty state",
      "setLoadingView": "View — loading state",
      "setErrorView": "View — error state"
    },
    "advanced": {
      "setTextFormatters": "List<CometChatTextFormatter> — custom text formatters",
      "setDateTimeFormatter": "DateTimeFormatterCallback — custom date/time formatting",
      "setMentionAllLabelId": "String id, String mentionAllLabel — custom mention-all label",
      "setHintText": "String — search bar hint text"
    },
    "style": {
      "setStyle": {
        "type": "@StyleRes int",
        "parent": "CometChatSearchStyle"
      }
    }
  },
  "events": [],
  "sdkListeners": []
}

Where It Fits

CometChatSearch is a composite search component. It searches across conversations and messages in real time and emits the selected result via setOnConversationClicked or setOnMessageClicked. Wire it to navigation so tapping a conversation opens the message view, or tapping a message scrolls to it in context.

Kotlin
Java

ChatActivity.kt

class ChatActivity : AppCompatActivity() {

    private lateinit var search: CometChatSearch
    private lateinit var messageHeader: CometChatMessageHeader
    private lateinit var messageList: CometChatMessageList
    private lateinit var messageComposer: CometChatMessageComposer

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_chat)

        search = findViewById(R.id.cometchat_search)
        messageHeader = findViewById(R.id.message_header)
        messageList = findViewById(R.id.message_list)
        messageComposer = findViewById(R.id.message_composer)

        search.setOnConversationClicked { view, position, conversation ->
            val user = conversation.conversationWith as? User
            user?.let {
                messageHeader.setUser(it)
                messageList.setUser(it)
                messageComposer.setUser(it)
            }
        }

        search.setOnMessageClicked { view, position, baseMessage ->
            // Navigate to the message in context
        }
    }
}

ChatActivity.java

public class ChatActivity extends AppCompatActivity {

    private CometChatSearch search;
    private CometChatMessageHeader messageHeader;
    private CometChatMessageList messageList;
    private CometChatMessageComposer messageComposer;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_chat);

        search = findViewById(R.id.cometchat_search);
        messageHeader = findViewById(R.id.message_header);
        messageList = findViewById(R.id.message_list);
        messageComposer = findViewById(R.id.message_composer);

        search.setOnConversationClicked((view, position, conversation) -> {
            if (conversation.getConversationWith() instanceof User) {
                User user = (User) conversation.getConversationWith();
                messageHeader.setUser(user);
                messageList.setUser(user);
                messageComposer.setUser(user);
            }
        });

        search.setOnMessageClicked((view, position, baseMessage) -> {
            // Navigate to the message in context
        });
    }
}

Quick Start

Add the component to your layout XML:

activity_search.xml

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:id="@+id/main"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".ui.activity.SearchActivity">

    <com.cometchat.chatuikit.search.CometChatSearch
        android:id="@+id/cometchat_search"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        app:layout_constraintTop_toTopOf="parent"/>

</androidx.constraintlayout.widget.ConstraintLayout>

Prerequisites: CometChat SDK initialized with CometChatUIKit.init(), a user logged in, and the cometchat-chat-uikit-android dependency added. To add programmatically in an Activity:

Kotlin
Java

SearchActivity.kt

class SearchActivity : AppCompatActivity() {
    private lateinit var binding: ActivitySearchBinding

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        binding = ActivitySearchBinding.inflate(layoutInflater)
        setContentView(binding.root)
    }
}

SearchActivity.java

public class SearchActivity extends AppCompatActivity {
    private ActivitySearchBinding binding;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        binding = ActivitySearchBinding.inflate(getLayoutInflater());
        setContentView(binding.getRoot());
    }
}

Actions and Events

Callback Methods

`setOnConversationClicked`

Fires when a user taps a conversation from the search results. Primary navigation hook — set the active conversation and render the message view.

Kotlin
Java

SearchActivity.kt

binding.cometchatSearch.setOnConversationClicked { view, position, conversation ->
    Log.i(TAG, "onCreate: Conversation Clicked !")
}

SearchActivity.java

binding.cometchatSearch.setOnConversationClicked((view, position, conversation) -> {
    Log.d(TAG, "onCreate: Conversation Clicked !");
});

What this does: Replaces the default conversation-click behavior. When a user taps a conversation item, your custom lambda executes. The callback receives the view, position, and Conversation object.

`setOnMessageClicked`

Fires when a user taps a message from the search results. Use to navigate to the message in context.

Kotlin
Java

SearchActivity.kt

binding.cometchatSearch.setOnMessageClicked { view, position, baseMessage ->
    Log.i(TAG, "onCreate: Message Clicked !")
}

SearchActivity.java

binding.cometchatSearch.setOnMessageClicked((view, position, baseMessage) -> {
    Log.d(TAG, "onCreate: Message Clicked !");
});

What this does: Registers a callback that fires when the user taps a message in the search results. The callback receives the view, position, and BaseMessage object.

`setOnBackPressListener`

Fires when the user presses the back button in the search bar. Default: no predefined behavior.

Kotlin
Java

SearchActivity.kt

binding.cometchatSearch.setOnBackPressListener {
    Log.i(TAG, "onCreate: Back Pressed !")
}

SearchActivity.java

binding.cometchatSearch.setOnBackPressListener(() -> {
    Log.d(TAG, "onCreate: Back Pressed !");
});

`setOnError`

Fires on internal errors (network failure, auth issue, SDK exception).

Kotlin
Java

SearchActivity.kt

binding.cometchatSearch.onError = OnError {
    Log.i(TAG, "onCreate: Error Occurred ! ${it.message}")
}

SearchActivity.java

binding.cometchatSearch.setOnError((e -> {
    Log.e(TAG, "onCreate: ", e);
}));

`setOnLoadMessages`

Fires when the message list is successfully fetched and loaded, helping track when message search results are ready.

Kotlin
Java

SearchActivity.kt

binding.cometchatSearch.setOnLoadMessages(OnLoad<BaseMessage> { list ->
    Log.i(TAG, "Messages loaded: ${list.size}")
})

SearchActivity.java

binding.cometchatSearch.setOnLoadMessages(list -> {
    Log.d(TAG, "Messages loaded: " + list.size());
});

`setOnLoadConversations`

Fires when the conversation list is successfully fetched and loaded, helping track when conversation search results are ready.

Kotlin
Java

SearchActivity.kt

binding.cometchatSearch.setOnLoadConversations(OnLoad<Conversation> { list ->
    Log.i(TAG, "Conversations loaded: ${list.size}")
})

SearchActivity.java

binding.cometchatSearch.setOnLoadConversations(list -> {
    Log.d(TAG, "Conversations loaded: " + list.size());
});

`setOnEmpty`

Fires when the search returns no results, enabling custom handling such as showing a placeholder.

Kotlin
Java

SearchActivity.kt

binding.cometchatSearch.onEmpty = OnEmpty {
    Log.i(TAG, "onCreate: No Results Found !")
}

SearchActivity.java

binding.cometchatSearch.setOnEmpty(() -> {
    Log.d(TAG, "onCreate: Empty Result !");
});

Verify: After setting an action callback, trigger the corresponding user interaction (tap a conversation result, tap a message result, press back, cause an error, or search for a term with no results) and confirm your custom logic executes.

Global UI Events

The CometChatSearch component does not produce any global UI events.

SDK Events (Real-Time, Automatic)

The CometChatSearch component does not listen to any SDK events internally. Search results are fetched on demand when the user types a query.

Functionality

Small functional customizations such as toggling visibility of UI elements and configuring search scope.

Methods	Description	Code
`setEmptyStateVisibility`	Hides the empty state when search returns no results	`.setEmptyStateVisibility(View.GONE);`
`setErrorStateVisibility`	Hides the error state on search failure	`.setErrorStateVisibility(View.GONE);`
`setSearchFilters`	List of filters rendered as chips in the search component	`.setSearchFilters(filters);`
`setInitialSearchFilter`	The filter which will be active by default on load	`.setInitialSearchFilter(UIKitConstants.SearchFilter.MESSAGES);`
`setSearchIn`	List of entities in which the search should be performed	`.setSearchIn(scopes);`
`setHideGroupType`	Hides the group type icon in conversation leading view	`.setHideGroupType(true);`
`setHideUserStatus`	Hides the user’s online/offline status indicator	`.setHideUserStatus(true);`

Verify: After calling a visibility or functionality method, confirm the corresponding UI element is shown or hidden, or the search scope is correctly applied.

Custom View Slots

Each slot replaces a section of the default UI. Conversation item slots use the ConversationsSearchViewHolderListener pattern (createView + bindView). Message item slots use the MessagesSearchViewHolderListener pattern.

Slot	Method	Replaces
Conversation item view	`setConversationItemView(ConversationsSearchViewHolderListener)`	Entire conversation item row
Text message item	`setTextMessageItemView(MessagesSearchViewHolderListener<TextMessage>)`	Text message item
Image message item	`setImageMessageItemView(MessagesSearchViewHolderListener<MediaMessage>)`	Image message item
Audio message item	`setAudioMessageItemView(MessagesSearchViewHolderListener<MediaMessage>)`	Audio message item
Video message item	`setVideoMessageItemView(MessagesSearchViewHolderListener<MediaMessage>)`	Video message item
Document message item	`setDocumentMessageItemView(MessagesSearchViewHolderListener<MediaMessage>)`	Document message item
Link message item	`setLinkMessageItemView(MessagesSearchViewHolderListener<TextMessage>)`	Link message item
Initial view	`setInitialView(@LayoutRes int)`	Initial state before search
Empty view	`setEmptyView(@LayoutRes int)`	Empty state
Loading view	`setLoadingView(View)`	Loading spinner
Error view	`setErrorView(View)`	Error state

`setConversationItemView`

Replace the entire conversation item row in search results.

Kotlin
Java

SearchActivity.kt

binding.cometchatSearch.setConversationItemView(object : ConversationsSearchViewHolderListener() {
    override fun createView(context: Context?, listItem: View?): View? {
        return layoutInflater.inflate(R.layout.custom_conversation_search_item, null)
    }

    override fun bindView(
        context: Context?,
        createdView: View?,
        conversation: Conversation?,
        holder: RecyclerView.ViewHolder?,
        conversationList: List<Conversation?>?,
        position: Int
    ) {
        val titleTv = createdView?.findViewById<android.widget.TextView>(R.id.tv_title)
        conversation?.let {
            if (it.conversationType == CometChatConstants.CONVERSATION_TYPE_USER) {
                titleTv?.text = (it.conversationWith as User).name
            } else {
                titleTv?.text = (it.conversationWith as Group).name
            }
        }
    }
})

SearchActivity.java

binding.cometchatSearch.setConversationItemView(new ConversationsSearchViewHolderListener() {
    @Override
    public View createView(Context context, View listItem) {
        LayoutInflater layoutInflater = (LayoutInflater) context.getSystemService(Context.LAYOUT_INFLATER_SERVICE);
        return layoutInflater.inflate(R.layout.custom_conversation_search_item, null);
    }

    @Override
    public void bindView(Context context, View createdView, Conversation conversation, RecyclerView.ViewHolder holder, List<Conversation> conversationList, int position) {
        android.widget.TextView titleTv = createdView.findViewById(R.id.tv_title);
        if (conversation != null) {
            if (conversation.getConversationType().equals(CometChatConstants.CONVERSATION_TYPE_USER)) {
                titleTv.setText(((User) conversation.getConversationWith()).getName());
            } else {
                titleTv.setText(((Group) conversation.getConversationWith()).getName());
            }
        }
    }
});

What this does: Registers a ConversationsSearchViewHolderListener for conversation items in search results. The createView method inflates a custom layout, and bindView populates it with the conversation name based on whether it’s a user or group conversation.

`setTextMessageItemView`

Replace the text message item view in search results. Define a custom layout XML:

custom_message_item_view.xml

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:orientation="horizontal"
    android:padding="16dp"
    android:background="#E8E4F3">

    <TextView
        android:id="@+id/tv_sender_name"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="George Alan:"
        android:textColor="#6B4FBB"
        android:textSize="16sp"
        android:textStyle="bold"
        android:layout_marginEnd="4dp" />

    <TextView
        android:id="@+id/tv_message"
        android:layout_width="0dp"
        android:layout_height="wrap_content"
        android:layout_weight="1"
        android:text="That works for me. Yes, let's go a..."
        android:textColor="#4A4A4A"
        android:textSize="16sp"
        android:ellipsize="end"
        android:maxLines="1" />
</LinearLayout>

Kotlin
Java

SearchActivity.kt

binding.cometchatSearch.setTextMessageItemView(object : MessagesSearchViewHolderListener<TextMessage>() {
    override fun createView(
        context: Context?,
        listItem: View?
    ): View? {
        return layoutInflater.inflate(R.layout.custom_message_item_view, null)
    }

    override fun bindView(
        context: Context?,
        createdView: View?,
        message: TextMessage?,
        holder: RecyclerView.ViewHolder?,
        messagesList: List<BaseMessage?>?,
        position: Int
    ) {
        val titleTv = createdView?.findViewById<android.widget.TextView>(R.id.tv_sender_name)
        val messageTv = createdView?.findViewById<android.widget.TextView>(R.id.tv_message)

        titleTv?.text = message?.sender?.name
        messageTv?.text = message?.text
    }
})

SearchActivity.java

binding.cometchatSearch.setTextMessageItemView(new MessagesSearchViewHolderListener<TextMessage>() {
    @Override
    public View createView(Context context, View listItem) {
        LayoutInflater layoutInflater = (LayoutInflater) context.getSystemService(Context.LAYOUT_INFLATER_SERVICE);
        return layoutInflater.inflate(R.layout.custom_message_item_view, null);
    }

    @Override
    public void bindView(Context context, View createdView, TextMessage message, RecyclerView.ViewHolder holder, List<BaseMessage> messagesList, int position) {
        android.widget.TextView titleTv = createdView.findViewById(R.id.tv_sender_name);
        android.widget.TextView messageTv = createdView.findViewById(R.id.tv_message);

        if (message != null) {
            titleTv.setText(message.getSender().getName());
            messageTv.setText(message.getText());
        }
    }
});

What this does: Registers a MessagesSearchViewHolderListener for text messages. The createView method inflates the custom layout, and bindView populates the sender name and message text from the TextMessage object.

Other Message Item Views

The following message item view methods follow the same MessagesSearchViewHolderListener pattern as setTextMessageItemView:

Method	Message Type	Generic Type
`setImageMessageItemView`	Image Message	`MessagesSearchViewHolderListener<MediaMessage>`
`setVideoMessageItemView`	Video Message	`MessagesSearchViewHolderListener<MediaMessage>`
`setAudioMessageItemView`	Audio Message	`MessagesSearchViewHolderListener<MediaMessage>`
`setDocumentMessageItemView`	Document Message	`MessagesSearchViewHolderListener<MediaMessage>`
`setLinkMessageItemView`	Link Message	`MessagesSearchViewHolderListener<TextMessage>`

`setInitialView`

Sets a custom view displayed when the search component is rendered and no search has been performed.

Kotlin
Java

binding.cometchatSearch.setInitialView(R.layout.your_initial_view)

binding.cometchatSearch.setInitialView(R.layout.your_initial_view);

`setEmptyView`

Configures a custom view displayed when the search returns no results.

Kotlin
Java

binding.cometchatSearch.setEmptyView(R.layout.your_empty_view)

binding.cometchatSearch.setEmptyView(R.layout.your_empty_view);

`setLoadingView`

Sets a custom loading view displayed when search results are being fetched.

Kotlin
Java

binding.cometchatSearch.setLoadingView(loadingView)

binding.cometchatSearch.setLoadingView(loadingView);

`setErrorView`

Defines a custom error state view that appears when an issue occurs while searching.

Kotlin
Java

binding.cometchatSearch.setErrorView(errorView)

binding.cometchatSearch.setErrorView(errorView);

Verify: After setting any custom view slot, confirm the custom view renders in the correct position within the search result items, and the data binding populates correctly for each result.

Common Patterns

Messages-only search

Kotlin
Java

binding.cometchatSearch.setSearchFilters(
    listOf(UIKitConstants.SearchFilter.MESSAGES)
)
binding.cometchatSearch.setInitialSearchFilter(UIKitConstants.SearchFilter.MESSAGES)

binding.cometchatSearch.setSearchFilters(
    Arrays.asList(UIKitConstants.SearchFilter.MESSAGES)
);
binding.cometchatSearch.setInitialSearchFilter(UIKitConstants.SearchFilter.MESSAGES);

Filter by message type

Kotlin
Java

binding.cometchatSearch.setMessagesRequestBuilder(
    MessagesRequest.MessagesRequestBuilder().setLimit(10)
)

binding.cometchatSearch.setMessagesRequestBuilder(
    new MessagesRequest.MessagesRequestBuilder().setLimit(10)
);

Scope search to a specific user

Kotlin
Java

binding.cometchatSearch.setUid("user123")

binding.cometchatSearch.setUid("user123");

Scope search to a specific group

Kotlin
Java

binding.cometchatSearch.setGuid("group123")

binding.cometchatSearch.setGuid("group123");

Advanced Methods

Search Scope

`setUid`

Scopes the search to a specific user’s conversation.

Kotlin
Java

binding.cometchatSearch.setUid("user123")

binding.cometchatSearch.setUid("user123");

`setGuid`

Scopes the search to a specific group’s conversation.

Kotlin
Java

binding.cometchatSearch.setGuid("group123")

binding.cometchatSearch.setGuid("group123");

Request Builders

`setConversationsRequestBuilder`

Sets a ConversationsRequest.ConversationsRequestBuilder to filter conversation search results. Pass the builder instance — not the result of .build(). For all available builder options, refer to the ConversationRequestBuilder documentation.

Kotlin
Java

binding.cometchatSearch.setConversationsRequestBuilder(
    ConversationsRequest.ConversationsRequestBuilder().setLimit(10)
)

binding.cometchatSearch.setConversationsRequestBuilder(
    new ConversationsRequest.ConversationsRequestBuilder().setLimit(10)
);

`setMessagesRequestBuilder`

Sets a MessagesRequest.MessagesRequestBuilder to filter message search results. For all available builder options, refer to the MessagesRequestBuilder documentation.

Kotlin
Java

binding.cometchatSearch.setMessagesRequestBuilder(
    MessagesRequest.MessagesRequestBuilder().setLimit(5)
)

binding.cometchatSearch.setMessagesRequestBuilder(
    new MessagesRequest.MessagesRequestBuilder().setLimit(5)
);

Text Formatters

`setTextFormatters`

Enables developers to define and apply text formatters that dynamically modify or transform message content before rendering it in the UI. Text formatters can be used for:

Automatically converting URLs into clickable links
Applying Markdown or rich text styling
Replacing certain words or patterns with emojis or predefined text
Censoring specific words for moderation

For implementation details, refer to the MentionsFormatter Guide.

Date/Time Formatting

`setDateTimeFormatter`

Provides a custom implementation of DateTimeFormatterCallback to configure how time and date values are displayed in search results.

Kotlin
Java

import java.text.SimpleDateFormat
import java.util.*

binding.cometchatSearch.setDateTimeFormatter(object : DateTimeFormatterCallback {

    private val fullTimeFormatter = SimpleDateFormat("hh:mm a", Locale.getDefault())
    private val dateFormatter = SimpleDateFormat("dd MMM yyyy", Locale.getDefault())

    override fun time(timestamp: Long): String {
        return fullTimeFormatter.format(Date(timestamp))
    }

    override fun today(timestamp: Long): String {
        return "Today"
    }

    override fun yesterday(timestamp: Long): String {
        return "Yesterday"
    }

    override fun lastWeek(timestamp: Long): String {
        return "Last Week"
    }

    override fun otherDays(timestamp: Long): String {
        return dateFormatter.format(Date(timestamp))
    }

    override fun minutes(diffInMinutesFromNow: Long, timestamp: Long): String {
        return "$diffInMinutesFromNow mins ago"
    }

    override fun hours(diffInHourFromNow: Long, timestamp: Long): String {
        return "$diffInHourFromNow hrs ago"
    }
})

import java.text.SimpleDateFormat;
import java.util.Date;
import java.util.Locale;

binding.cometchatSearch.setDateTimeFormatter(new DateTimeFormatterCallback() {

    private final SimpleDateFormat fullTimeFormatter = new SimpleDateFormat("hh:mm a", Locale.getDefault());
    private final SimpleDateFormat dateFormatter = new SimpleDateFormat("dd MMM yyyy", Locale.getDefault());

    @Override
    public String time(long timestamp) {
        return fullTimeFormatter.format(new Date(timestamp));
    }

    @Override
    public String today(long timestamp) {
        return "Today";
    }

    @Override
    public String yesterday(long timestamp) {
        return "Yesterday";
    }

    @Override
    public String lastWeek(long timestamp) {
        return "Last Week";
    }

    @Override
    public String otherDays(long timestamp) {
        return dateFormatter.format(new Date(timestamp));
    }

    @Override
    public String minutes(long diffInMinutesFromNow, long timestamp) {
        return diffInMinutesFromNow + " mins ago";
    }

    @Override
    public String hours(long diffInHourFromNow, long timestamp) {
        return diffInHourFromNow + " hrs ago";
    }
});

What this does: Provides a custom date/time formatter that displays “Today”, “Yesterday”, “Last Week” for recent messages, a “dd MMM yyyy” format for older messages, and relative time strings like “5 mins ago” or “2 hrs ago” for recent activity.

Other Advanced Methods

Method	Type	Description
`setMentionAllLabelId`	`String id, String mentionAllLabel`	Sets a custom label for the “mention all” feature for a specific ID
`setHintText`	`String`	Sets the hint text displayed in the search bar

Style

The component uses XML theme styles. Define a custom style with parent CometChatSearchStyle in themes.xml, then apply with setStyle().

themes.xml

    <style name="CustomSearchStyle" parent="CometChatSearchStyle">
        <item name="cometchatSearchBackgroundColor">#EDEAFA</item>

        <item name="cometchatSearchFilterChipTextAppearance">@style/textStyleTimesNewRoman</item>

        <item name="cometchatSearchSectionHeaderTextAppearance">@style/textStyleTimesNewRoman</item>
        <item name="cometchatSearchSectionHeaderBackgroundColor">#EDEAFA</item>

        <item name="cometchatSearchConversationItemBackgroundColor">#EDEAFA</item>
        <item name="cometchatSearchConversationSubtitleTextAppearance">@style/textStyleTimesNewRoman</item>
        <item name="cometchatSearchConversationTitleTextAppearance">@style/textStyleTimesNewRoman</item>
        <item name="cometchatSearchConversationTimestampTextAppearance">?attr/cometchatTextAppearanceCaption1Bold</item>

        <item name="cometchatSearchSeeMoreTextAppearance">@style/textStyleTimesNewRoman</item>

        <item name="cometchatSearchMessageItemBackgroundColor">#EDEAFA</item>
        <item name="cometchatSearchMessageTitleTextAppearance">@style/textStyleTimesNewRoman</item>
        <item name="cometchatSearchMessageSubtitleTextAppearance">@style/textStyleTimesNewRoman</item>
        <item name="cometchatSearchMessageTimestampTextAppearance">@style/textStyleTimesNewRoman</item>

        <item name="cometchatSearchBarTextAppearance">@style/textStyleTimesNewRoman</item>
    </style>

    <style name="textStyleTimesNewRoman">
        <item name="android:fontFamily">@font/times_new_roman_regular</item>
    </style>

What this does: Defines a custom search style that sets a light purple background color (#EDEAFA) for the search component, conversation items, and message items, and applies a Times New Roman font to all text elements including filter chips, section headers, conversation titles/subtitles, message titles/subtitles, timestamps, “see more” text, and the search bar.

Kotlin
Java

binding.cometchatSearch.setStyle(R.style.CustomSearchStyle)

binding.cometchatSearch.setStyle(R.style.CustomSearchStyle);

To view all available style attributes, visit the attributes file.

Programmatic Style Properties

In addition to XML theme styles, the component exposes programmatic setters for fine-grained control: Search Bar

Method	Type	Description
`setBackgroundColor`	`@ColorInt int`	Background color of the component
`setSearchBarBackgroundColor`	`@ColorInt int`	Background color of the search bar
`setSearchBarStrokeWidth`	`@Dimension int`	Stroke width of the search bar border
`setSearchBarStrokeColor`	`@ColorInt int`	Stroke color of the search bar border
`setSearchBarCornerRadius`	`@Dimension int`	Corner radius of the search bar
`setSearchBarTextColor`	`@ColorInt int`	Text color of the search bar input
`setSearchBarTextAppearance`	`@StyleRes int`	Text appearance of the search bar input
`setSearchBarHintTextColor`	`@ColorInt int`	Hint text color of the search bar
`setBackIcon`	`Drawable`	Custom back icon drawable
`setBackIconTint`	`@ColorInt int`	Tint color for the back icon
`setClearIcon`	`Drawable`	Custom clear icon drawable
`setClearIconTint`	`@ColorInt int`	Tint color for the clear icon
`setSearchIcon`	`Drawable`	Custom search icon drawable
`setSearchIconTint`	`@ColorInt int`	Tint color for the search icon

Filter Chips

Method	Type	Description
`setFilterChipBackgroundColor`	`@ColorInt int`	Background color of filter chips
`setFilterChipSelectedBackgroundColor`	`@ColorInt int`	Background color of selected filter chips
`setFilterChipTextColor`	`@ColorInt int`	Text color of filter chips
`setFilterChipSelectedTextColor`	`@ColorInt int`	Text color of selected filter chips
`setFilterChipTextAppearance`	`@StyleRes int`	Text appearance of filter chips
`setFilterChipStrokeColor`	`@ColorInt int`	Stroke color of filter chips
`setFilterChipSelectedStrokeColor`	`@ColorInt int`	Stroke color of selected filter chips
`setFilterChipStrokeWidth`	`@Dimension int`	Stroke width of filter chips
`setFilterChipCornerRadius`	`@Dimension int`	Corner radius of filter chips

Section Headers

Method	Type	Description
`setSectionHeaderTextColor`	`@ColorInt int`	Text color for section headers
`setSectionHeaderTextAppearance`	`@StyleRes int`	Text appearance for section headers
`setSectionHeaderBackgroundColor`	`@ColorInt int`	Background color for section headers

Conversation Items

Method	Type	Description
`setConversationItemBackgroundColor`	`@ColorInt int`	Background color for conversation items
`setConversationTitleTextColor`	`@ColorInt int`	Text color for conversation titles
`setConversationTitleTextAppearance`	`@StyleRes int`	Text appearance for conversation titles
`setConversationSubtitleTextColor`	`@ColorInt int`	Text color for conversation subtitles
`setConversationSubtitleTextAppearance`	`@StyleRes int`	Text appearance for conversation subtitles
`setConversationTimestampTextColor`	`@ColorInt int`	Text color for conversation timestamps
`setConversationTimestampTextAppearance`	`@StyleRes int`	Text appearance for conversation timestamps

Message Items

Method	Type	Description
`setMessageItemBackgroundColor`	`@ColorInt int`	Background color for message items
`setMessageTitleTextColor`	`@ColorInt int`	Text color for message titles
`setMessageTitleTextAppearance`	`@StyleRes int`	Text appearance for message titles
`setMessageSubtitleTextColor`	`@ColorInt int`	Text color for message subtitles
`setMessageSubtitleTextAppearance`	`@StyleRes int`	Text appearance for message subtitles
`setMessageTimestampTextColor`	`@ColorInt int`	Text color for message timestamps
`setMessageTimestampTextAppearance`	`@StyleRes int`	Text appearance for message timestamps
`setMessageLinkTextColor`	`@ColorInt int`	Text color for links in messages
`setMessageLinkTextAppearance`	`@StyleRes int`	Text appearance for links in messages

Other Style Properties

Method	Type	Description
`setAvatarStyle`	`@StyleRes int`	Style for avatars in search results
`setBadgeStyle`	`@StyleRes int`	Style for badges in search results
`setSeeMoreTextColor`	`@ColorInt int`	Text color for “See more” links
`setSeeMoreTextAppearance`	`@StyleRes int`	Text appearance for “See more” links
`setDateSeparatorTextColor`	`@ColorInt int`	Text color for date separators
`setDateSeparatorBackgroundColor`	`@ColorInt int`	Background color for date separators
`setDateSeparatorTextAppearance`	`@StyleRes int`	Text appearance for date separators
`setEmptyStateTextColor`	`@ColorInt int`	Title text color for the empty state
`setEmptyStateTextAppearance`	`@StyleRes int`	Title text appearance for the empty state
`setEmptyStateSubtitleTextColor`	`@ColorInt int`	Subtitle text color for the empty state
`setEmptyStateSubtitleTextAppearance`	`@StyleRes int`	Subtitle text appearance for the empty state
`setEmptyStateIcon`	`Drawable`	Icon for the empty state
`setEmptyStateIconTint`	`@ColorInt int`	Tint for the empty state icon
`setErrorStateTextColor`	`@ColorInt int`	Title text color for the error state
`setErrorStateTextAppearance`	`@StyleRes int`	Title text appearance for the error state
`setErrorStateSubtitleTextColor`	`@ColorInt int`	Subtitle text color for the error state
`setErrorStateSubtitleTextAppearance`	`@StyleRes int`	Subtitle text appearance for the error state
`setErrorStateIcon`	`Drawable`	Icon for the error state
`setErrorStateIconTint`	`@ColorInt int`	Tint for the error state icon

Customization Matrix

What to change	Where	Property/API	Example
Override behavior on conversation tap	Activity/Fragment	`setOnConversationClicked`	`setOnConversationClicked { v, pos, conv -> ... }`
Override behavior on message tap	Activity/Fragment	`setOnMessageClicked`	`setOnMessageClicked { v, pos, msg -> ... }`
Override back press behavior	Activity/Fragment	`setOnBackPressListener`	`setOnBackPressListener { ... }`
Scope search to a user	Activity/Fragment	`setUid(String)`	`.setUid("user123")`
Scope search to a group	Activity/Fragment	`setGuid(String)`	`.setGuid("group123")`
Hide user online status	Activity/Fragment	`setHideUserStatus(boolean)`	`.setHideUserStatus(true)`
Hide group type icon	Activity/Fragment	`setHideGroupType(boolean)`	`.setHideGroupType(true)`
Set search filters	Activity/Fragment	`setSearchFilters(List)`	`.setSearchFilters(filters)`
Set initial active filter	Activity/Fragment	`setInitialSearchFilter(SearchFilter)`	`.setInitialSearchFilter(UIKitConstants.SearchFilter.MESSAGES)`
Set search scope	Activity/Fragment	`setSearchIn(List<SearchScope>)`	`.setSearchIn(scopes)`
Filter conversation results	Activity/Fragment	`setConversationsRequestBuilder`	See Request Builders code above
Filter message results	Activity/Fragment	`setMessagesRequestBuilder`	See Request Builders code above
Custom conversation item view	Activity/Fragment	`setConversationItemView(ConversationsSearchViewHolderListener)`	See `setConversationItemView` code above
Custom text message item view	Activity/Fragment	`setTextMessageItemView(MessagesSearchViewHolderListener)`	See `setTextMessageItemView` code above
Custom image message item view	Activity/Fragment	`setImageMessageItemView(MessagesSearchViewHolderListener)`	See `setTextMessageItemView` pattern
Custom video message item view	Activity/Fragment	`setVideoMessageItemView(MessagesSearchViewHolderListener)`	See `setTextMessageItemView` pattern
Custom audio message item view	Activity/Fragment	`setAudioMessageItemView(MessagesSearchViewHolderListener)`	See `setTextMessageItemView` pattern
Custom document message item view	Activity/Fragment	`setDocumentMessageItemView(MessagesSearchViewHolderListener)`	See `setTextMessageItemView` pattern
Custom link message item view	Activity/Fragment	`setLinkMessageItemView(MessagesSearchViewHolderListener)`	See `setTextMessageItemView` pattern
Custom initial view	Activity/Fragment	`setInitialView(@LayoutRes int)`	`.setInitialView(R.layout.your_initial_view)`
Custom loading view	Activity/Fragment	`setLoadingView(View)`	`.setLoadingView(loadingView)`
Custom empty view	Activity/Fragment	`setEmptyView(@LayoutRes int)`	`.setEmptyView(R.layout.your_empty_view)`
Custom error view	Activity/Fragment	`setErrorView(View)`	`.setErrorView(errorView)`
Empty state visibility	Activity/Fragment	`setEmptyStateVisibility(int)`	`.setEmptyStateVisibility(View.GONE)`
Error state visibility	Activity/Fragment	`setErrorStateVisibility(int)`	`.setErrorStateVisibility(View.GONE)`
Change colors, fonts, spacing	`themes.xml`	`CometChatSearchStyle`	`<item name="cometchatSearchBackgroundColor">#EDEAFA</item>`
Apply a custom style	Activity/Fragment	`setStyle(int styleRes)`	`binding.cometchatSearch.setStyle(R.style.CustomSearchStyle)`
Search bar background	Activity/Fragment	`setSearchBarBackgroundColor`	`.setSearchBarBackgroundColor(color)`
Filter chip colors	Activity/Fragment	`setFilterChip*` methods	`.setFilterChipBackgroundColor(color)`
Section header style	Activity/Fragment	`setSectionHeader*` methods	`.setSectionHeaderTextColor(color)`
Conversation item style	Activity/Fragment	`setConversation*` methods	`.setConversationTitleTextColor(color)`
Message item style	Activity/Fragment	`setMessage*` methods	`.setMessageTitleTextColor(color)`
Date/time formatting	Activity/Fragment	`setDateTimeFormatter(DateTimeFormatterCallback)`	See `setDateTimeFormatter` code above
Text formatters	Activity/Fragment	`setTextFormatters(List)`	See Text Formatters section
Search bar hint text	Activity/Fragment	`setHintText(String)`	`.setHintText("Search...")`
Mention-all label	Activity/Fragment	`setMentionAllLabelId(String, String)`	`.setMentionAllLabelId(id, label)`
Callback on messages loaded	Activity/Fragment	`setOnLoadMessages(OnLoad<BaseMessage>)`	`.setOnLoadMessages { list -> ... }`
Callback on conversations loaded	Activity/Fragment	`setOnLoadConversations(OnLoad<Conversation>)`	`.setOnLoadConversations { list -> ... }`

Accessibility

The component renders a search bar with filter chips and scrollable result lists for conversations and messages. The search input is focusable and supports keyboard input. Filter chips respond to tap gestures and announce their selected state. For custom views provided via setConversationItemView or message item view setters, ensure you set android:contentDescription on visual-only elements so TalkBack can announce them. The default views handle this automatically.

Next Steps

Conversations

Browse recent conversations

Users

Browse and search available users

Groups

Browse and search available groups

Message List

Display messages in a conversation

​Where It Fits

​Quick Start

​Actions and Events

​Callback Methods

​setOnConversationClicked

​setOnMessageClicked

​setOnBackPressListener

​setOnError

​setOnLoadMessages

​setOnLoadConversations

​setOnEmpty

​Global UI Events

​SDK Events (Real-Time, Automatic)

​Functionality

​Custom View Slots

​setConversationItemView

​setTextMessageItemView

​Other Message Item Views

​setInitialView

​setEmptyView

​setLoadingView

​setErrorView

​Common Patterns

​Messages-only search

​Filter by message type

​Scope search to a specific user

​Scope search to a specific group

​Advanced Methods

​Search Scope

​setUid

​setGuid

​Request Builders

​setConversationsRequestBuilder

​setMessagesRequestBuilder

​Text Formatters

​setTextFormatters

​Date/Time Formatting

​setDateTimeFormatter

​Other Advanced Methods

​Style

​Programmatic Style Properties

​Customization Matrix

​Accessibility

​Next Steps

Conversations

Users

Groups

Message List

Where It Fits

Quick Start

Actions and Events

Callback Methods

`setOnConversationClicked`

`setOnMessageClicked`

`setOnBackPressListener`

`setOnError`

`setOnLoadMessages`

`setOnLoadConversations`

`setOnEmpty`

Global UI Events

SDK Events (Real-Time, Automatic)

Functionality

Custom View Slots

`setConversationItemView`

`setTextMessageItemView`

Other Message Item Views

`setInitialView`

`setEmptyView`

`setLoadingView`

`setErrorView`

Common Patterns

Messages-only search

Filter by message type

Scope search to a specific user

Scope search to a specific group

Advanced Methods

Search Scope

`setUid`

`setGuid`

Request Builders

`setConversationsRequestBuilder`

`setMessagesRequestBuilder`

Text Formatters

`setTextFormatters`

Date/Time Formatting

`setDateTimeFormatter`

Other Advanced Methods

Style

Programmatic Style Properties

Customization Matrix

Accessibility

Next Steps