Search Customization

Search customization in v14 is built around Search and WithComponents. ChannelList still toggles search with showChannelSearch, but the old ChannelSearch and additionalChannelSearchProps APIs were removed.

Best Practices

Override the smallest search layer you need: Search, SearchBar, or result components.
Reuse DefaultSearchResultItems when you only want to replace one source's visuals.

Configure Search Through `WithComponents`

If you only need to change props such as placeholder or exitSearchOnInputBlur, wrap the built-in Search component and override it through WithComponents.

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

const ChannelListSearch = () => (
  <Search
    directMessagingChannelType="team"
    exitSearchOnInputBlur
    placeholder="Search teammates, channels, and messages..."
  />
);

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

Customize Search Result Items

The Search UI groups results by source. To replace only one source's item component, provide a custom SearchSourceResultList.

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

const CustomChannelResult = ({ item }) => (
  <button className="channel-search-result" type="button">
    #{item.data?.name ?? item.id}
  </button>
);

const SearchResultList = () => (
  <SearchSourceResultList
    SearchResultItems={{
      ...DefaultSearchResultItems,
      channels: CustomChannelResult,
    }}
  />
);

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

Render Search Outside `ChannelList`

You can also render Search anywhere inside Chat when search should not be owned by the channel sidebar.

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

<Chat client={client}>
  <aside>
    <Search placeholder="Search everything..." />
    <ChannelList filters={filters} options={options} sort={sort} />
  </aside>
  <Channel>
    <Window>
      <ChannelHeader />
      <MessageList />
      <MessageComposer />
    </Window>
    <Thread />
  </Channel>
</Chat>;

Go Lower-Level When You Need Custom Data Sources

If you need to change what is searched, not just how results render, create a custom SearchController and pass it to Chat. The advanced guide covers custom search sources, filter builders, and source-specific result rendering.

See Advanced Search.