# Search Customization

Search customization in v14 is built around [`Search`](/chat/docs/sdk/react/components/utility-components/channel-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`.

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

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

```tsx
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](/chat/docs/sdk/react/guides/advanced-search/).


---

This page was last updated at 2026-05-22T16:32:14.107Z.

For the most recent version of this documentation, visit [https://getstream.io/chat/docs/sdk/react/guides/customization/channel-search/](https://getstream.io/chat/docs/sdk/react/guides/customization/channel-search/).