Search - CometChat Docs

AI Integration Quick Reference

{
  "component": "CometChatSearch",
  "package": "@cometchat/chat-uikit-react",
  "import": "import { CometChatSearch } from \"@cometchat/chat-uikit-react\";",
  "description": "Unified search across conversations and messages with filter chips, scoped search, and customizable result views.",
  "cssRootClass": ".cometchat-search",
  "primaryOutput": {
    "prop": "onConversationClicked",
    "type": "(event: CometChatSearchConversationClickEvent) => void"
  },
  "props": {
    "data": {
      "searchIn": {
        "type": "CometChatSearchScope[]",
        "default": "[] (both conversations and messages)",
        "note": "Empty array shows both sections"
      },
      "searchFilters": {
        "type": "CometChatSearchFilter[]",
        "default": "all available filters"
      },
      "initialSearchFilter": {
        "type": "CometChatSearchFilter",
        "default": "undefined"
      },
      "defaultSearchText": {
        "type": "string",
        "default": "undefined"
      },
      "uid": {
        "type": "string",
        "default": "undefined",
        "note": "Scope search to a specific user's conversation"
      },
      "guid": {
        "type": "string",
        "default": "undefined",
        "note": "Scope search to a specific group's conversation"
      },
      "lastMessageDateTimeFormat": {
        "type": "CometChatDateFormatConfig",
        "default": "DD/MM/YYYY for all date ranges in search context"
      },
      "messageSentAtDateTimeFormat": {
        "type": "CometChatDateFormatConfig",
        "default": "undefined"
      },
      "conversationsRequestBuilder": {
        "type": "CometChat.ConversationsRequestBuilder",
        "default": "SDK default",
        "note": "Pass the builder instance, not the result of .build()"
      },
      "messagesRequestBuilder": {
        "type": "CometChat.MessagesRequestBuilder",
        "default": "SDK default",
        "note": "Pass the builder instance, not the result of .build()"
      },
      "textFormatters": {
        "type": "CometChatTextFormatter[]",
        "default": "undefined"
      }
    },
    "callbacks": {
      "onBack": "() => void",
      "onConversationClicked": "(event: CometChatSearchConversationClickEvent) => void",
      "onMessageClicked": "(event: CometChatSearchMessageClickEvent) => void",
      "onError": "((error: CometChat.CometChatException) => void) | null"
    },
    "visibility": {
      "hideBackButton": { "type": "boolean", "default": false },
      "hideUserStatus": { "type": "boolean", "default": false },
      "hideGroupType": { "type": "boolean", "default": false },
      "hideReceipts": { "type": "boolean", "default": false }
    },
    "viewSlots": {
      "initialView": "ReactNode",
      "loadingView": "ReactNode",
      "emptyView": "ReactNode",
      "errorView": "ReactNode",
      "conversationItemView": "(conversation: CometChat.Conversation) => ReactNode",
      "conversationLeadingView": "(conversation: CometChat.Conversation) => ReactNode",
      "conversationTitleView": "(conversation: CometChat.Conversation) => ReactNode",
      "conversationSubtitleView": "(conversation: CometChat.Conversation) => ReactNode",
      "conversationTrailingView": "(conversation: CometChat.Conversation) => ReactNode",
      "messageItemView": "(message: CometChat.BaseMessage) => ReactNode",
      "messageLeadingView": "(message: CometChat.BaseMessage) => ReactNode",
      "messageTitleView": "(message: CometChat.BaseMessage) => ReactNode",
      "messageSubtitleView": "(message: CometChat.BaseMessage) => ReactNode",
      "messageTrailingView": "(message: CometChat.BaseMessage) => ReactNode",
      "conversationOptions": "(conversation: CometChat.Conversation) => CometChatSearchConversationOption[]"
    }
  },
  "events": [],
  "sdkListeners": [],
  "types": {
    "CometChatSearchScope": "'conversations' | 'messages'",
    "CometChatSearchFilter": "'messages' | 'conversations' | 'unread' | 'groups' | 'photos' | 'videos' | 'links' | 'files' | 'audio'",
    "CometChatSearchConversationClickEvent": {
      "conversation": "CometChat.Conversation",
      "searchKeyword": "string"
    },
    "CometChatSearchMessageClickEvent": {
      "message": "CometChat.BaseMessage",
      "searchKeyword": "string"
    },
    "CometChatSearchConversationOption": {
      "id": "string",
      "title": "string",
      "iconURL": "string | undefined",
      "onClick": "(conversation: CometChat.Conversation) => void"
    },
    "CometChatDateFormatConfig": {
      "today": "string | undefined",
      "yesterday": "string | undefined",
      "lastWeek": "string | undefined",
      "otherDays": "string | undefined",
      "relativeTime": {
        "minute": "string | undefined",
        "minutes": "string | undefined",
        "hour": "string | undefined",
        "hours": "string | undefined"
      }
    }
  }
}

Overview

CometChatSearch is a unified search component. It searches across conversations and messages, displaying results in separate sections with filter chips for scoping. It emits the selected result via onConversationClicked or onMessageClicked — both include the searchKeyword in the event payload. Wire it to CometChatConversations or CometChatMessageList to navigate to the matched result.

Live Preview — interact with the default search component.Open in Storybook ↗

The component handles:

Dual-section results (conversations + messages)
Filter chips for scoping (messages, conversations, unread, groups, photos, videos, links, files, audio)
Scoped search via uid or guid
Custom request builders for both conversations and messages
Customizable result item views

Usage

Flat API

import { CometChatSearch } from "@cometchat/chat-uikit-react";

function SearchPanel() {
  return (
    <CometChatSearch
      onConversationClicked={(event) => {
        // event.conversation — the matched conversation
        // event.searchKeyword — the search term used
        navigateToConversation(event.conversation);
      }}
      onMessageClicked={(event) => {
        // event.message — the matched message
        // event.searchKeyword — the search term used
        scrollToMessage(event.message);
      }}
    />
  );
}

Compound Composition

import { CometChatSearch } from "@cometchat/chat-uikit-react";

function SearchPanel() {
  return (
    <CometChatSearch.Root
      onConversationClicked={handleConversationClick}
      onMessageClicked={handleMessageClick}
    >
      <CometChatSearch.ConversationsList />
      <CometChatSearch.MessagesList />
    </CometChatSearch.Root>
  );
}

Scoped Search Example

import { CometChatSearch } from "@cometchat/chat-uikit-react";

function ConversationSearch({ userId }: { userId: string }) {
  return (
    <CometChatSearch
      uid={userId}
      searchIn={["messages"]}
      onMessageClicked={(event) => {
        scrollToMessage(event.message);
      }}
      onBack={() => closeSearch()}
    />
  );
}

Full Layout Example

import { useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import {
  CometChatConversations,
  CometChatSearch,
  CometChatMessageList,
} from "@cometchat/chat-uikit-react";

function ChatApp() {
  const [showSearch, setShowSearch] = useState(false);
  const [user, setUser] = useState<CometChat.User | undefined>();
  const [group, setGroup] = useState<CometChat.Group | undefined>();

  return (
    <div style={{ display: "flex", height: "100vh" }}>
      <div style={{ width: 360 }}>
        {showSearch ? (
          <CometChatSearch
            onConversationClicked={(event) => {
              const entity = event.conversation.getConversationWith();
              if (event.conversation.getConversationType() === "user") {
                setUser(entity as CometChat.User);
                setGroup(undefined);
              } else {
                setGroup(entity as CometChat.Group);
                setUser(undefined);
              }
              setShowSearch(false);
            }}
            onBack={() => setShowSearch(false)}
          />
        ) : (
          <CometChatConversations
            onSearchBarClicked={() => setShowSearch(true)}
            onItemClick={(conversation) => {
              const entity = conversation.getConversationWith();
              if (conversation.getConversationType() === "user") {
                setUser(entity as CometChat.User);
                setGroup(undefined);
              } else {
                setGroup(entity as CometChat.Group);
                setUser(undefined);
              }
            }}
          />
        )}
      </div>
      <div style={{ flex: 1 }}>
        <CometChatMessageList user={user} group={group} />
      </div>
    </div>
  );
}

Filtering

Search Scope

Control which result sections appear using searchIn:

{/* Only show conversation results */}
<CometChatSearch searchIn={["conversations"]} />

{/* Only show message results */}
<CometChatSearch searchIn={["messages"]} />

{/* Both (default) */}
<CometChatSearch searchIn={[]} />

Filter Chips

Control which filter chips are available:

<CometChatSearch
  searchFilters={["messages", "conversations", "unread", "photos"]}
  initialSearchFilter="messages"
/>

Scoped Search

Scope the search to a specific user or group conversation:

{/* Search within a specific user's conversation */}
<CometChatSearch uid="user-123" />

{/* Search within a specific group's conversation */}
<CometChatSearch guid="group-456" />

Custom Request Builders

Pass custom request builders for fine-grained control:

<CometChatSearch
  conversationsRequestBuilder={
    new CometChat.ConversationsRequestBuilder()
      .setLimit(15)
      .setConversationType("user")
  }
  messagesRequestBuilder={
    new CometChat.MessagesRequestBuilder()
      .setLimit(20)
      .setSearchKeyword("hello")
  }
/>

Actions and Events

Callback Props

Prop	Signature	Fires when
`onConversationClicked`	`(event: CometChatSearchConversationClickEvent) => void`	User clicks a conversation result
`onMessageClicked`	`(event: CometChatSearchMessageClickEvent) => void`	User clicks a message result
`onBack`	`() => void`	Back button is clicked
`onError`	`((error: CometChat.CometChatException) => void) \| null`	SDK error occurs

Events Emitted

None.

Events Received

None.

SDK Listeners (Automatic)

None — the component fetches results on search input change and does not subscribe to real-time SDK listeners.

Customization

View Props

Use view props to replace sections of the default UI while keeping the component’s behavior intact:

<CometChatSearch
  initialView={<RecentSearches />}
  emptyView={<NoResults />}
  loadingView={<SearchSkeleton />}
  errorView={<SearchError />}
  conversationItemView={(conversation) => (
    <MyCustomConversationResult conversation={conversation} />
  )}
  messageItemView={(message) => (
    <MyCustomMessageResult message={message} />
  )}
/>

Slot	Signature	Replaces
`initialView`	`ReactNode`	Pre-search state (before user types)
`loadingView`	`ReactNode`	Loading shimmer
`emptyView`	`ReactNode`	Empty state (no results)
`errorView`	`ReactNode`	Error state
`conversationItemView`	`(conversation) => ReactNode`	Entire conversation result row
`conversationLeadingView`	`(conversation) => ReactNode`	Avatar section of conversation result
`conversationTitleView`	`(conversation) => ReactNode`	Title of conversation result
`conversationSubtitleView`	`(conversation) => ReactNode`	Subtitle of conversation result
`conversationTrailingView`	`(conversation) => ReactNode`	Trailing section of conversation result
`messageItemView`	`(message) => ReactNode`	Entire message result row
`messageLeadingView`	`(message) => ReactNode`	Avatar section of message result
`messageTitleView`	`(message) => ReactNode`	Title of message result
`messageSubtitleView`	`(message) => ReactNode`	Subtitle of message result
`messageTrailingView`	`(message) => ReactNode`	Trailing section of message result

messageItemView

Replace the entire message list item in search results.

TypeScript
CSS

import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatSearch } from "@cometchat/chat-uikit-react";

function SearchCustomMessageItem() {
  const getMessageItemView = (message: CometChat.BaseMessage) => (
    <div className="cometchat-search__message-list-item">
      <div className="cometchat-search__message-list-item-sender">
        {message.getSender()?.getName()}:
      </div>
      <div className="cometchat-search__message-list-item-text">
        {message instanceof CometChat.TextMessage
          ? (message as CometChat.TextMessage).getText()
          : message.getType()}
      </div>
    </div>
  );

  return <CometChatSearch messageItemView={getMessageItemView} />;
}

.cometchat-search__message-list-item {
  background: var(--cometchat-extended-primary-color-100);
  border-bottom: 1px solid var(--cometchat-border-color-highlight);
  padding: var(--cometchat-padding-3) var(--cometchat-padding-4);
  display: flex;
  justify-content: flex-start;
  gap: var(--cometchat-padding-2);
}

.cometchat-search__message-list-item-sender {
  color: var(--cometchat-text-color-highlight);
  font: var(--cometchat-font-body-regular);
}

.cometchat-search__message-list-item-text {
  color: var(--cometchat-text-color-secondary);
  font: var(--cometchat-font-body-regular);
}

messageLeadingView

Replace the message avatar / left section.

TypeScript
CSS

import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatSearch } from "@cometchat/chat-uikit-react";

function SearchCustomMessageLeading() {
  const getMessageLeadingView = (message: CometChat.BaseMessage) => (
    <div className="cometchat-search__message-list-item-leading-view">
      <img src="ICON_URL" alt="" />
    </div>
  );

  return <CometChatSearch messageLeadingView={getMessageLeadingView} />;
}

.cometchat-search__message-list-item-leading-view {
  height: 48px;
  width: 48px;
  border-radius: var(--cometchat-radius-2);
  background: var(--cometchat-extended-primary-color-500);
  display: flex;
  align-items: center;
  justify-content: center;
}

.cometchat-search__message-list-item-leading-view img {
  height: 32px;
  width: 32px;
}

messageTitleView

Replace the message title text.

TypeScript
CSS

import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatSearch } from "@cometchat/chat-uikit-react";

function SearchCustomMessageTitle() {
  const getMessageTitleView = (message: CometChat.BaseMessage) => (
    <div className="cometchat-search__message-list-item-title">
      <div className="cometchat-search__message-list-item-title-text">
        {message.getSender()?.getName()}
      </div>
      <span>|</span>
      <div className="cometchat-search__message-list-item-title-role">
        {message.getSender().getRole() ?? "Pro User"}
      </div>
    </div>
  );

  return <CometChatSearch messageTitleView={getMessageTitleView} />;
}

.cometchat-search__message-list-item-title {
  display: flex;
  align-items: center;
  gap: var(--cometchat-spacing-1);
}

.cometchat-search__message-list-item-title-text {
  font: var(--cometchat-font-heading4-medium);
  color: var(--cometchat-text-color-secondary);
}

.cometchat-search__message-list-item-title-role {
  font: var(--cometchat-font-heading4-medium);
  color: var(--cometchat-text-color-highlight);
  text-decoration: underline;
}

messageSubtitleView

Replace the message subtitle text.

TypeScript
CSS

import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatSearch } from "@cometchat/chat-uikit-react";

function SearchCustomMessageSubtitle() {
  const getMessageSubtitleView = (message: CometChat.BaseMessage) => (
    <div className="cometchat-search__message-list-item-subtitle">
      <div className="cometchat-search__message-list-item-subtitle-sender">
        {message.getSender()?.getName()}:
      </div>
      <div className="cometchat-search__message-list-item-subtitle-text">
        {message instanceof CometChat.TextMessage
          ? (message as CometChat.TextMessage).getText()
          : message.getType()}
      </div>
    </div>
  );

  return <CometChatSearch messageSubtitleView={getMessageSubtitleView} />;
}

.cometchat-search__message-list-item-subtitle {
  background: var(--cometchat-extended-primary-color-100);
  padding: var(--cometchat-padding-1);
  display: flex;
  justify-content: flex-start;
  gap: var(--cometchat-padding-2);
  width: 100%;
}

.cometchat-search__message-list-item-subtitle-sender {
  color: var(--cometchat-text-color-highlight);
  font: var(--cometchat-font-body-regular);
}

.cometchat-search__message-list-item-subtitle-text {
  color: var(--cometchat-text-color-secondary);
  font: var(--cometchat-font-body-regular);
}

Compound Composition

For full layout control, use sub-components. Omit any sub-component to hide that section:

<CometChatSearch.Root onConversationClicked={handleClick}>
  {/* Only show conversations — no messages section */}
  <CometChatSearch.ConversationsList />
</CometChatSearch.Root>

Available sub-components:

Sub-component	Description	Props	Flat API equivalent
`Root`	Context provider and container	All Root props + `children`	—
`ConversationsList`	Conversation results section	`className`	—
`MessagesList`	Message results section	`className`	—

The flat API and Root accept the same props — all view slots are directly on Root. There are no separate convenience props.

CSS Styling

Override design tokens on the component selector:

.cometchat-search {
  --cometchat-background-color-01: #1a1a2e;
  --cometchat-text-color-primary: #ffffff;
}

.cometchat-search__filters {
  gap: 8px;
}

Props

All props are optional.

The flat API and Root accept the same props — all view slots are directly on Root. There are no separate convenience props.

searchIn

Which result sections to show. Empty array (default) shows both conversations and messages.


Type	`CometChatSearchScope[]`
Default	`[]` (both)

Filter chips to display in the filter bar.


Type	`CometChatSearchFilter[]`
Default	All available filters

initialSearchFilter

Pre-select a filter chip on mount.


Type	`CometChatSearchFilter`
Default	`undefined`

defaultSearchText

Pre-populate the search input with this text.


Type	`string`
Default	`undefined`

uid

Scope search to a specific user’s conversation. When set, conversation filters are hidden.


Type	`string`
Default	`undefined`

guid

Scope search to a specific group’s conversation. When set, conversation filters are hidden.


Type	`string`
Default	`undefined`

hideBackButton

Hide the back button in the header.


Type	`boolean`
Default	`false`

hideUserStatus

Hide user online/offline status indicators in conversation results.


Type	`boolean`
Default	`false`

hideGroupType

Hide group type badge in conversation results.


Type	`boolean`
Default	`false`

hideReceipts

Hide message delivery/read receipts in conversation results.


Type	`boolean`
Default	`false`

textFormatters

Text formatters applied to conversation subtitles.


Type	`CometChatTextFormatter[]`
Default	`undefined`

lastMessageDateTimeFormat

Custom date/time format for the last message timestamp in conversation results.


Type	`CometChatDateFormatConfig`
Default	`DD/MM/YYYY` for all date ranges in search context

messageSentAtDateTimeFormat

Custom date/time format for the sent-at timestamp in message results.


Type	`CometChatDateFormatConfig`
Default	`undefined`

conversationsRequestBuilder

Custom request builder for conversation search. Pass the builder instance — not the result of .build().


Type	`CometChat.ConversationsRequestBuilder`
Default	SDK default

messagesRequestBuilder

Custom request builder for message search. Pass the builder instance — not the result of .build().


Type	`CometChat.MessagesRequestBuilder`
Default	SDK default

conversationOptions

Function that returns context menu options for each conversation result item.


Type	`(conversation: CometChat.Conversation) => CometChatSearchConversationOption[]`
Default	`undefined`

<CometChatSearch
  conversationOptions={(conversation) => [
    {
      id: "open",
      title: "Open",
      onClick: (conv) => navigateToConversation(conv),
    },
  ]}
/>

onBack

Callback when the back button is clicked.


Type	`() => void`
Default	`undefined`

onConversationClicked

Callback when a conversation result item is clicked. The event includes the search keyword.


Type	`(event: CometChatSearchConversationClickEvent) => void`
Default	`undefined`

onMessageClicked

Callback when a message result item is clicked. The event includes the search keyword.


Type	`(event: CometChatSearchMessageClickEvent) => void`
Default	`undefined`

onError

Callback when an SDK error occurs during search.


Type	`((error: CometChat.CometChatException) => void) \| null`
Default	`null`

CSS Selectors

Target	Selector
Root container	`.cometchat-search`
Header	`.cometchat-search__header`
Search bar	`.cometchat-search__search-bar`
Filter chips	`.cometchat-search__filters`
Results container	`.cometchat-search__results`
Conversations section	`.cometchat-search__conversations-section`
Messages section	`.cometchat-search__messages-section`
Initial state	`.cometchat-search__initial-state`
Empty state	`.cometchat-search__empty-state`
Error state	`.cometchat-search__error-state`
Loading state	`.cometchat-search__loading-state`

Next Steps

Conversations

Display the conversation list alongside search

Message List

Navigate to matched messages in the message list

Theming

Customize colors, fonts, and spacing

​Overview

​Usage

​Flat API

​Compound Composition

​Scoped Search Example

​Full Layout Example

​Filtering

​Search Scope

​Filter Chips

​Scoped Search

​Custom Request Builders

​Actions and Events

​Callback Props

​Events Emitted

​Events Received

​SDK Listeners (Automatic)

​Customization

​View Props

​messageItemView

​messageLeadingView

​messageTitleView

​messageSubtitleView

​Compound Composition

​CSS Styling

​Props

​searchIn

​searchFilters

​initialSearchFilter

​defaultSearchText

​uid

​guid

​hideBackButton

​hideUserStatus

​hideGroupType

​hideReceipts

​textFormatters

​lastMessageDateTimeFormat

​messageSentAtDateTimeFormat

​conversationsRequestBuilder

​messagesRequestBuilder

​conversationOptions

​onBack

​onConversationClicked

​onMessageClicked

​onError

​CSS Selectors

​Next Steps

Conversations

Message List

Theming

Overview

Usage

Flat API

Compound Composition

Scoped Search Example

Full Layout Example

Filtering

Search Scope

Filter Chips

Scoped Search

Custom Request Builders

Actions and Events

Callback Props

Events Emitted

Events Received

SDK Listeners (Automatic)

Customization

View Props

messageItemView

messageLeadingView

messageTitleView

messageSubtitleView

Compound Composition

CSS Styling

Props

searchIn

searchFilters

initialSearchFilter

defaultSearchText

uid

guid

hideBackButton

hideUserStatus

hideGroupType

hideReceipts

textFormatters

lastMessageDateTimeFormat

messageSentAtDateTimeFormat

conversationsRequestBuilder

messagesRequestBuilder

conversationOptions

onBack

onConversationClicked

onMessageClicked

onError

CSS Selectors

Next Steps