# Search

`Search` renders the SDK's search UI for channels, users, and messages. You can enable it inside [`ChannelList`](/chat/docs/sdk/react/components/core-components/channel-list/) with `showChannelSearch`, or render it directly anywhere inside [`Chat`](/chat/docs/sdk/react/components/core-components/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`:

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

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

Render `Search` standalone:

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

| Prop                         | Description                                                                                         | Type      |
| ---------------------------- | --------------------------------------------------------------------------------------------------- | --------- |
| `directMessagingChannelType` | Channel type used when a user result starts a direct-message conversation. Defaults to `messaging`. | `string`  |
| `disabled`                   | Disables the search input.                                                                          | `boolean` |
| `exitSearchOnInputBlur`      | Exits search when the empty input loses focus. Defaults to `false`.                                 | `boolean` |
| `placeholder`                | Custom placeholder text for the input. If omitted, the SDK uses the translated `Search` label.      | `string`  |

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

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

| Override key                          | Default component                     |
| ------------------------------------- | ------------------------------------- |
| `SearchBar`                           | `SearchBar`                           |
| `SearchResults`                       | `SearchResults`                       |
| `SearchResultsHeader`                 | `SearchResultsHeader`                 |
| `SearchResultsPresearch`              | `SearchResultsPresearch`              |
| `SearchSourceResults`                 | `SearchSourceResults`                 |
| `SearchSourceResultList`              | `SearchSourceResultList`              |
| `SearchSourceResultListFooter`        | `SearchSourceResultListFooter`        |
| `SearchSourceResultsEmpty`            | `SearchSourceResultsEmpty`            |
| `SearchSourceResultsHeader`           | no default                            |
| `SearchSourceResultsLoadingIndicator` | `SearchSourceResultsLoadingIndicator` |

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

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


---

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

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