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

> Unified search across conversations and messages with filter chips, scoped search, and customizable result views.

<Accordion title="AI Integration Quick Reference">
  | Field | Value |
  | - | - |
  | Component | `CometChatSearch` |
  | Package | `@cometchat/chat-uikit-react` |
  | Import | `import { CometChatSearch } from "@cometchat/chat-uikit-react";` |
  | CSS root class | `.cometchat-search` |
  | Primary output | `onConversationClicked: (event: CometChatSearchConversationClickEvent) => void` — emits the clicked search result |
  | Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user |
  | Stitching | Wire `onConversationClicked` / `onMessageClicked` to open the selected result — see the [Search Messages guide](/ui-kit/react/guide-search-messages) |
  | Full props | See [Props](#props) |
</Accordion>

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

<Note>
  **These result callbacks are required to make the component useful.** `CometChatSearch` does not navigate on its own — clicking a result only fires `onConversationClicked` or `onMessageClicked`. Your app must handle navigation: open the [Conversations](/ui-kit/react/components/conversations) list or route to the matched entity, and pass the message's ID to [Message List](/ui-kit/react/components/message-list) via `goToMessageId` to scroll to the exact message. For an end-to-end walkthrough, see the [Search Messages guide](/ui-kit/react/guide-search-messages).
</Note>

<Warning>
  **Message search is plan-gated.** It requires **Search enabled on your CometChat plan** (check your app's plan in the [Dashboard](https://app.cometchat.com/)). Until it's enabled, the search API responds with **HTTP `402 Payment Required`** and no results appear — even when `CometChatSearch` is wired correctly.
</Warning>

<Info>
  **Live Preview** — interact with the default search component.

  [Open in Storybook ↗](https://storybook.cometchat.io/react/?path=/story/components-cometchatsearch--default)
</Info>

<iframe src="https://storybook.cometchat.io/react/iframe.html?id=components-cometchatsearch--default&viewMode=story&shortcuts=false&singleStory=true" className="w-full rounded-xl" loading="lazy" style={{height: "700px", border: "1px solid #e0e0e0"}} title="CometChat Search — Default" allow="clipboard-write" />

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

```tsx theme={null}
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

```tsx theme={null}
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

```tsx theme={null}
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

```tsx theme={null}
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`:

```tsx theme={null}
{/* 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:

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

### Scoped Search

Scope the search to a specific user or group conversation:

```tsx theme={null}
{/* 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:

```tsx theme={null}
<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:

```tsx theme={null}
<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.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-llms-scoped-indexes/JjWlPukYmAPwZawH/images/3d0a9273-search_message_item_view_custom_web_screens-bf216d1eab67d0d95362a3ef1996f752.png?fit=max&auto=format&n=JjWlPukYmAPwZawH&q=85&s=0db775371abadf85d6ec743b22223e9e" width="1280" height="800" data-path="images/3d0a9273-search_message_item_view_custom_web_screens-bf216d1eab67d0d95362a3ef1996f752.png" />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    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} />;
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css theme={null}
    .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);
    }
    ```
  </Tab>
</Tabs>

#### messageLeadingView

Replace the message avatar / left section.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-llms-scoped-indexes/-nSFFcS2LLIkMyn9/images/8ec51714-search_message_leading_view_custom_web_screens-af08d61c02454c807100907c1156d46d.png?fit=max&auto=format&n=-nSFFcS2LLIkMyn9&q=85&s=f7a1b143863da068636bd423163a7579" width="1280" height="800" data-path="images/8ec51714-search_message_leading_view_custom_web_screens-af08d61c02454c807100907c1156d46d.png" />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    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} />;
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css theme={null}
    .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;
    }
    ```
  </Tab>
</Tabs>

#### messageTitleView

Replace the message title text.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-llms-scoped-indexes/Fa6hxbnaPB6CCDby/images/0b1cf07c-search_message_title_view_custom_web_screens-df6cb1c0e91a105d4f708e47c62de992.png?fit=max&auto=format&n=Fa6hxbnaPB6CCDby&q=85&s=91439ad56ec74cd7881d84ddf97310b5" width="1280" height="800" data-path="images/0b1cf07c-search_message_title_view_custom_web_screens-df6cb1c0e91a105d4f708e47c62de992.png" />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    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} />;
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css theme={null}
    .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;
    }
    ```
  </Tab>
</Tabs>

#### messageSubtitleView

Replace the message subtitle text.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-llms-scoped-indexes/g_KAMkRj71rxDRMU/images/67721bd7-search_message_subtitle_view_custom_web_screens-96e7a678fc3920eb12db00b43c4f6860.png?fit=max&auto=format&n=g_KAMkRj71rxDRMU&q=85&s=f39cf6f81a59c6eab54b9ef1066a450d" width="1280" height="800" data-path="images/67721bd7-search_message_subtitle_view_custom_web_screens-96e7a678fc3920eb12db00b43c4f6860.png" />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    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} />;
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css theme={null}
    .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);
    }
    ```
  </Tab>
</Tabs>

### Compound Composition

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

```tsx theme={null}
<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` | — |

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

### CSS Styling

Override design tokens on the component selector:

```css theme={null}
.cometchat-search {
  --cometchat-background-color-01: #1a1a2e;
  --cometchat-text-color-primary: #ffffff;
}

.cometchat-search__filters {
  gap: 8px;
}
```

***

## Props

All props are optional.

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

***

### searchIn

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

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

***

### searchFilters

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

```tsx theme={null}
<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

<CardGroup cols={2}>
  <Card title="Conversations" icon="comments" href="/ui-kit/react/components/conversations">
    Display the conversation list alongside search
  </Card>

  <Card title="Message List" icon="list" href="/ui-kit/react/components/message-list">
    Navigate to matched messages in the message list
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Customize colors, fonts, and spacing
  </Card>
</CardGroup>


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