---
id: channel_search
sidebar_position: 5
title: ChannelSearch
---

import ImageShowcase from '@site/src/components/ImageShowcase';

import GHComponentLink from '../../_docusaurus-components/GHComponentLink';

import ImageInactiveSearchBarNoAppMenu from '../../assets/inactive-searchbar-no-app-menu.png';
import ImageInactiveSearchBarWithAppMenu from '../../assets/inactive-searchbar-with-app-menu.png';
import ImageActiveSearchBarNoText from '../../assets/active-searchbar-no-text.png';
import ImageActiveSearchBarWithText from '../../assets/active-searchbar-with-text.png';
import ImageSearchResultsInlineThemeV2 from '../../assets/search-results-inline-theme-v2.png';
import ImageSearchResultsPopupThemeV2 from '../../assets/search-results-popup-theme-v2.png';
import ImageSearchResultsInlineThemeV1 from '../../assets/search-results-inline-theme-v1.png';
import ImageSearchResultsPopupThemeV1 from '../../assets/search-results-popup-theme-v1.png';
import ImageSearchResultsLoadingThemeV2 from '../../assets/search-results-loading-theme-v2.png';
import ImageSearchResultsLoadingThemeV1 from '../../assets/search-results-loading-theme-v1.png';
import ImageSearchResultsEmptyThemeV2 from '../../assets/search-results-empty-theme-v2.png';
import ImageSearchResultsEmptyThemeV1 from '../../assets/search-results-empty-theme-v1.png';

`ChannelSearch` is a UI component that searches for chat users and displays the results in a list. It can be used standalone or in the `ChannelList` via the `showChannelSearch` prop (default is false).
The input searches for users by default, but you can utilize the `searchForChannels` prop to also search for `channels`. Completely override the querying via the `searchFunction` prop.
Selection of a search result will set the active channel with the selected user, or if a channel is an option and is selected, set the active channel with the existing channel.

## Basic Usage

** Example 1 ** - used via the `showChannelSearch` prop.

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

## ChannelSearch according to theme version

The `ChannelSearch` component renders 2 components:

1. the search input
2. the search results list

If opted in the use of [theme version 2](../../theming/introduction.mdx), the `ChannelSearch` will render a more complex search input component called [`SearchBar`](./#searchbar-component). Otherwise, the [`SearchInput`](./#searchinput-component) is rendered.

### Search input vs.SearchResults state

The input naturally transitions between 3 states regardless of theme version:

| Input state   | Input                            | Search results |
| ------------- | -------------------------------- | -------------- |
| inactive      | not focused                      | not rendered   |
| focused       | focused and empty                | not rendered   |
| active search | contains non-empty search string | rendered       |

It is possible to jump directly from active search state to inactive by pressing the Esc key or by erasing the search input value. The search results container is shown only if the search input contains non-empty string.

Once the search results container is rendered it transitions between the following states:

| Search results state      | Search results                                                    |
| ------------------------- | ----------------------------------------------------------------- |
| loading                   | the search API call is in progress                                |
| empty search (result)     | the search API call returned an empty array                       |
| non-empty search (result) | the search API call returned an array of channel and user objects |

### SearchInput component

The <GHComponentLink text='SearchInput source code' path='/ChannelSearch/SearchInput.tsx'/> shows that the component renders a single text input element. User can provide a custom [`SearchInput`](./#searchinput) component implementation though.

### SearchBar component

The `SearchBar` contains multiple elements - buttons and text input. The buttons are conditionally rendered based on user interaction with the `ChannelSearch` components. All the button icons displayed in the `SearchBar` are customizable. User can provide a custom [`SearchBar`](./#searchbar) component implementation.

#### SearchBar states

The `SearchBar` transitions between the same states as the `SearchInput`, but renders more elements.

##### 1. Inactive state:

The `SearchBar` is rendered with [app menu icon](./#menuicon) if a custom [`AppMenu` component](./#appmenu) is provided to the `ChannelSearch`. Otherwise, only search input is visible.

<ImageShowcase
  border
  items={[
    {
      image: ImageInactiveSearchBarNoAppMenu,
      caption: <span>Inactive search bar with an app menu</span>,
      alt: 'Image of an inactive search bar state with an app menu',
    },
    {
      image: ImageInactiveSearchBarWithAppMenu,
      caption: <span>Inactive search bar without an app menu</span>,
      alt: 'Image of an inactive search bar state without an app menu',
    },
  ]}
/>

##### 2. Active state:

Once the input is focused, a return-arrow button occurs with [`ExitSearchIcon`](./#exitsearchicon) to exit the active state. Note the app menu icon is actually replaced by the return arrow button. After typing the search query a clear-input button with [`ClearInputIcon`](./#clearinputicon) appears inside the search input.

<ImageShowcase
  border
  items={[
    {
      image: ImageActiveSearchBarNoText,
      caption: <span>Active search bar with empty input</span>,
      alt: 'Image of an active search bar state with empty input',
    },
    {
      image: ImageActiveSearchBarWithText,
      caption: <span>Active search bar with search query</span>,
      alt: 'Image of an active search bar with search query',
    },
  ]}
/>

By clicking the return-arrow button, the user returns to the inactive search state. By clicking the clear-input button the input is cleared but kept focused with return-arrow still displayed (with possibility to exit the search altogether).

The active search UI state can be exited by pressing the `Escape` key as well.

### SearchResults component

The following states are reflected in the `SearchResults`:

1. The search query being in progress (can be customized with [`SearchLoading`](./#searchloading) )
2. The empty search result (can be customized with [`SearchEmpty`](./#searchempty))
3. The listing of found channels (if [`searchForChannels`](./#searchforchannels) is set to `true`) and users

The look of the latter can be customized by providing [`SearchResultsHeader`](./#searchresultsheader), [`SearchResultItem`](./#searchresultitem), [`SearchResultsList`](./#searchresultslist)) (renders the list of `SearchResultItem`).

The default styling of the first two states are as follows:

<ImageShowcase
  border
  items={[
    {
      image: ImageSearchResultsLoadingThemeV1,
      caption: <span>Search results list content when loading (theme v1)</span>,
      alt: 'Image of search results list content when loading',
    },
    {
      image: ImageSearchResultsEmptyThemeV1,
      caption: <span>Empty search results (theme v1)</span>,
      alt: 'Image of empty search results',
    },
    {
      image: ImageSearchResultsLoadingThemeV2,
      caption: <span>Search results list content when loading (theme v2)</span>,
      alt: 'Image of search results list content when loading',
    },
    {
      image: ImageSearchResultsEmptyThemeV2,
      caption: <span>Empty search results (theme v2)</span>,
      alt: 'Image of empty search results',
    },
  ]}
/>

#### Search results in popup

The search results can be rendered in place of the channel list or above the channel list in a floating container. This behavior is toggled by [`popupResults`](./#popupResults) prop.

<ImageShowcase
  border
  items={[
    {
      image: ImageSearchResultsInlineThemeV1,
      caption: <span>Search results displayed inline (theme v1)</span>,
      alt: 'Image of search results displayed inline (theme v1)',
    },
    {
      image: ImageSearchResultsPopupThemeV1,
      caption: <span>Search results displayed floating above the channel list (theme v1)</span>,
      alt: 'Image of search results displayed floating above the channel list (theme v1)',
    },
    {
      image: ImageSearchResultsInlineThemeV2,
      caption: <span>Search results displayed inline (theme v2)</span>,
      alt: 'Image of search results displayed inline (theme v2)',
    },
    {
      image: ImageSearchResultsPopupThemeV2,
      caption: <span>Search results displayed floating above the channel list (theme v2)</span>,
      alt: 'Image of search results displayed floating above the channel list (theme v2)',
    },
  ]}
/>

#### Keep the search results open on channel select

The `ChannelSearch` offers possibility to keep the search results open meanwhile the user clicks between the search results. This behavior is controlled by [`clearSearchOnClickOutside`](./#clearsearchonclickoutside) flag. The selected channel is added to the channel list if it was not present there before the search.

## Props

### AppMenu

Application menu / drop-down to be displayed when clicked on [`MenuIcon`](./#menuicon). Prop is consumed only by the [`SearchBar` component](./#searchbar). The `SearchBar` component is only available with the use of the [theming v2](../../theming/introduction.mdx). No default component is provided by the SDK. The library does not provide any CSS for `AppMenu`. Consult the customization tutorial on how to [add AppMenu to your application](../../guides/customization/channel-search.mdx/#adding-menu). The component is passed a prop `close`, which is a function that can be called to hide the app menu (e.g. on menu item selection).

| Type                  | Default     |
| --------------------- | ----------- |
| `React.ComponentType` | `undefined` |

### channelType

The type of `channel` to create on user result selection.

| Type                                                            | Default     |
| --------------------------------------------------------------- | ----------- |
| `livestream` \| `messaging` \| `team` \| `gaming` \| `commerce` | `messaging` |

### ClearInputIcon

Custom icon component used as a content of the button used to clear the search input. Prop is consumed only by the [`SearchBar` component](./#searchbar). The `SearchBar` component is rendered with `themeVersion` `'2'` only.

| Type                  | Default                                                         |
| --------------------- | --------------------------------------------------------------- |
| `React.ComponentType` | <GHComponentLink text='XIcon' path='/ChannelSearch/icons.tsx'/> |

### clearSearchOnClickOutside

Signals that the search state / results should be cleared on every click outside the search input (e.g. selecting a search result or exiting the search UI), defaults to `true`. If set to `false`, the search results are kept in the UI meanwhile the user changes between the channels.

| Type      | Default |
| --------- | ------- |
| `boolean` | `true`  |

### disabled

Disables execution of the search queries and makes the search text input element disabled. Defaults to `false`.

| Type      | Default |
| --------- | ------- |
| `boolean` | `false` |

### ExitSearchIcon

Custom icon component used as a content of the button used to exit the search UI. Prop is consumed only by the [`SearchBar` component](./#searchbar). The `SearchBar` component is rendered with `themeVersion` `'2'` only.

| Type                  | Default                                                              |
| --------------------- | -------------------------------------------------------------------- |
| `React.ComponentType` | <GHComponentLink text='ReturnIcon' path='/ChannelSearch/icons.tsx'/> |

### MenuIcon

Custom icon component used as a content of the button used to invoke the [`AppMenu`](./#appmenu). Prop is consumed only by the [`SearchBar` component](./#searchbar). The `SearchBar` component is rendered with `themeVersion` `'2'` only. The menu icon button is displayed only if `AppMenu` component has been passed to `ChannelSearch` props.

| Type                  | Default                                                            |
| --------------------- | ------------------------------------------------------------------ |
| `React.ComponentType` | <GHComponentLink text='MenuIcon' path='/ChannelSearch/icons.tsx'/> |

### onSearch

Callback invoked with every search input change handler. SDK user can provide own implementation. The prop is used by the `ChannelList` component to set a flag determining that the search has been initiated. If the search has been initiated and search result are to be displayed instead of the list of loaded channels ([`popupResults` flag](./#popupresults) is set to `false`), then the list of loaded channels is not rendered. This logic is executed despite passing custom implementation of `onSearch` function to `ChanneList` props.

| Type                                          |
| --------------------------------------------- |
| `React.ChangeEventHandler<HTMLInputElement\>` |

### onSearchExit

Callback invoked when the search UI is deactivated. The `ChannelList` component uses it to set a flag that the search has been terminated and search results are not expected to be displayed in place of the list of loaded channels. And so the `ChannelList` renders the list of loaded channels. This logic is executed despite passing custom implementation of `onSearchExit` function to `ChanneList` props.

| Type         |
| ------------ |
| `() => void` |

### onSelectResult

Custom handler function to run on search result item selection. If not provided then the default selection handler takes care of:

1. loading the active channel
2. adding the selected channel to the channel list
3. clearing the search results, if [`clearSearchOnClickOutside` flag](./#clearsearchonclickoutside) is set to true (default)

| Type                                                                                                                                                                                                        |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| (<br/>&nbsp;&nbsp;&nbsp;&nbsp;`params: ChannelSearchFunctionParams<StreamChatGenerics\>,` <br/>&nbsp;&nbsp;&nbsp;&nbsp;`result: ChannelOrUserResponse<StreamChatGenerics\>`<br/>) => Promise<void\> \| void |

### placeholder

Custom placeholder text to be displayed in the search input. Can be passed down from `ChannelList` via its `additionalChannelSearchProps`. If using custom i18n translations, it is preferable to change the placeholder value in your translations files under the key `'Search'`.

| Type     | Default    |
| -------- | ---------- |
| `string` | `'Search'` |

### popupResults

Display search results as an absolutely positioned popup, defaults to false and shows inline.

| Type      | Default |
| --------- | ------- |
| `boolean` | `false` |

### SearchBar

Custom component to be rendered instead of the default <GHComponentLink text='SearchBar' path='/ChannelSearch/SearchBar.tsx'/>. This component is displayed only if `themeVersion` is `'2'`. With the theme version 1 only the `SearchInput` is rendered. The default `SearchBar` component is a composite of multiple buttons and a search input. You can find more information about its features in an [above section](./#searchbar-component).

| Type                                   | Default                                                                 |
| -------------------------------------- | ----------------------------------------------------------------------- |
| `React.ComponentType<SearchBarProps\>` | <GHComponentLink text='SearchBar' path='/ChannelSearch/SearchBar.tsx'/> |

### SearchEmpty

Custom UI component to display empty search results.

| Type                  | Default                                                                              |
| --------------------- | ------------------------------------------------------------------------------------ |
| `React.ComponentType` | <GHComponentLink text='DefaultSearchEmpty' path='/ChannelSearch/SearchResults.tsx'/> |

### searchForChannels

Boolean to search for channels as well as users in the server query, default is `false` and just searches for users.

| Type      | Default |
| --------- | ------- |
| `boolean` | `false` |

### searchFunction

Custom search function to override default. The first argument should expect an object of type `ChannelSearchFunctionParams`. It carries references to the `Dispatch<SetStateAction>` functions that allow to control the search state:

- `setQuery` - sets the search input value, the default value is an empty string
- `setResults` - sets the array of search results, the default value is an empty array
- `setSearching` - signals that the HTTP search request is in progress

| Type                                                                                                |
| --------------------------------------------------------------------------------------------------- |
| (`params: ChannelSearchFunctionParams, event: React.BaseSyntheticEvent` ) => Promise<void\> \| void |

### searchDebounceIntervalMs

The number of milliseconds to debounce the search query.

| Type     | Default |
|----------|---------|
| `number` | 300     |

### SearchInput

Custom UI component to display the search text input.

| Type                                    | Default                                                                     |
| --------------------------------------- | --------------------------------------------------------------------------- |
| `React.ComponentType<SearchInputProps>` | <GHComponentLink text='SearchInput' path='/ChannelSearch/SearchInput.tsx'/> |

### SearchLoading

Custom UI component to display the search loading state. Rendered within the `SearchResults` component.

| Type                  | Default                    |
| --------------------- | -------------------------- |
| `React.ComponentType` | a div with: 'Searching...' |

### searchQueryParams

Object containing filters/sort/options overrides for user / channel search.

The `filters` attribute (`SearchQueryParams.userFilters.filters`) can be either `UserFilters` object describing the filter query or a function with a single argument of the search / filter (query) string. The function is then expected to derive and return the `UserFilters` from the provided query string.

| Type                                    |
| --------------------------------------- |
| `SearchQueryParams<StreamChatGenerics>` |

### SearchResultsHeader

Custom UI component to display the search results header.

| Type                  | Default                                                                                      |
| --------------------- | -------------------------------------------------------------------------------------------- |
| `React.ComponentType` | <GHComponentLink text='DefaultSearchResultsHeader' path='/ChannelSearch/SearchResults.tsx'/> |

### SearchResultItem

Custom UI component to display a search result list item.

| Type                                                             | Default                                                                                   |
| ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `React.ComponentType<SearchResultItemProps<StreamChatGenerics>>` | <GHComponentLink text='DefaultSearchResultItem' path='/ChannelSearch/SearchResults.tsx'/> |

### SearchResultsList

Custom UI component to display all the search results.

| Type                                                              | Default                                                                                    |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `React.ComponentType<SearchResultsListProps<StreamChatGenerics>>` | <GHComponentLink text='DefaultSearchResultsList' path='/ChannelSearch/SearchResults.tsx'/> |
