Search

Search renders the SDK's search UI for channels, users, and messages. You can enable it inside ChannelList with showChannelSearch, or render it directly anywhere inside Chat when a searchController is available in context.

Best Practices

• Control rendering through ChannelList.showChannelSearch if you decide to render search as part of the ChannelList.
• Use WithComponents to customize search UI.
• Memoize custom SearchController instances to avoid resetting results.

Basic Usage

Enable search in ChannelList:

import {
  Channel,
  ChannelHeader,
  ChannelList,
  Chat,
  MessageInput,
  MessageList,
  Thread,
  Window,
} from "stream-chat-react";

<Chat client={client}>
  <ChannelList
    filters={filters}
    options={options}
    showChannelSearch
    sort={sort}
  />
  <Channel>
    <Window>
      <ChannelHeader />
      <MessageList />
      <MessageInput />
    </Window>
    <Thread />
  </Channel>
</Chat>;

Render Search standalone:

import { Chat, Search } from "stream-chat-react";

<Chat client={client}>
  <Search placeholder="Search channels, messages, and users..." />
</Chat>;

The Search component exposes a small prop surface:

Anatomy

Search renders two layers:

1. SearchBar for the input, clear button, and cancel button
2. SearchResults for pre-search state, per-source results, loading, and empty states

The default result items are grouped by search source type:

• channels
• messages
• users

When a user result is selected, the SDK creates or activates a direct-message channel using directMessagingChannelType. When a channel or message result is selected, the SDK activates that channel and updates the loaded channel list.

UI Customization

Search customization now flows through WithComponents / ComponentContext.

Override the main Search component to adjust its props:

import { ChannelList, Search, WithComponents } from "stream-chat-react";

const CustomSearch = () => (
  <Search
    exitSearchOnInputBlur
    placeholder="Search channels, people, and messages..."
  />
);

<WithComponents overrides={{ Search: CustomSearch }}>
  <ChannelList
    filters={filters}
    options={options}
    showChannelSearch
    sort={sort}
  />
</WithComponents>;

Override search subcomponents when you only want to customize a single layer:

Custom Result Items

Use SearchSourceResultList and DefaultSearchResultItems to replace only the result-item rendering while keeping the built-in search state, pagination, and source grouping.

import {
  ChannelList,
  DefaultSearchResultItems,
  SearchSourceResultList,
  WithComponents,
} from "stream-chat-react";

const CustomUserResult = ({ item }) => (
  <button className="custom-search-result" type="button">
    Invite {item.name ?? item.id}
  </button>
);

const CustomSearchSourceResultList = () => (
  <SearchSourceResultList
    SearchResultItems={{
      ...DefaultSearchResultItems,
      users: CustomUserResult,
    }}
  />
);

<WithComponents
  overrides={{ SearchSourceResultList: CustomSearchSourceResultList }}
>
  <ChannelList
    filters={filters}
    options={options}
    showChannelSearch
    sort={sort}
  />
</WithComponents>;

Data Management

Search reads from the searchController provided by Chat. For advanced data customization, provide your own SearchController instance to Chat and configure its sources there.

The advanced search guide covers:

• custom SearchController instances
• custom search sources
• dynamic filter builders
• advanced result rendering

See Advanced Search.