Search components

Search renders the search bar and, while a search is open, its results: channels, users and messages. It reads the SearchController that Chat provides, so it works anywhere inside Chat. ChannelNavigation renders it above the channel lists. Search explains the feature, and Search sources the controller and its sources.

Best practices

• Change what is searched on the controller and its sources, not in the components. Pass your own controller to Chat as searchController.
• Create your own controller once per client, for example with useMemo. A new controller on every render starts every search from scratch.
• Replace one part of the search UI with its override key rather than the whole Search.
• To set Search props on the Search that ChannelNavigation renders, register a component that renders Search with them under the Search key.

Basic usage

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

const SidebarSearch = () => (
  <Search exitSearchOnInputBlur placeholder="Search chats and people" />
);

const overrides = { Search: SidebarSearch };

export const WithSidebarSearch = ({ children }: PropsWithChildren) => (
  <WithComponents overrides={overrides}>{children}</WithComponents>
);

Rendered around ChannelNavigation, this replaces the search bar above the lists. Outside ChannelNavigation, render <Search /> wherever the layout needs it.

Search props:

Typing opens search and passes the text to the controller. The clear button empties the text. Cancel, or the Escape key, closes search.

Anatomy

Search provides SearchContext and renders SearchBar and SearchResults. Each part is read from an override key:

UI customization

Register replacements with WithComponents. The default of every key above except SearchSourceResultsHeader, which renders nothing, is exported under the same name, so a replacement can render the default with something added:

import type { PropsWithChildren } from "react";
import { SearchSourceResultsEmpty, WithComponents } from "stream-chat-react";

const EmptyWithHint = () => (
  <div className="search-empty">
    <SearchSourceResultsEmpty />
    <p>Try a shorter word, or search messages instead.</p>
  </div>
);

const overrides = { SearchSourceResultsEmpty: EmptyWithHint };

export const WithSearchHint = ({ children }: PropsWithChildren) => (
  <WithComponents overrides={overrides}>{children}</WithComponents>
);

A part reads the controller with useSearchContext(), and the source it renders with useSearchSourceResultsContext(). Reading search state in your own components has an example. To remove search from ChannelNavigation, register a Search that renders nothing.

Custom result items

SearchSourceResultList props:

DefaultSearchResultItems maps the built-in sources to their result components:

Each component also takes onSelect: (event: React.MouseEvent) => void, which runs instead of the default click. To replace one, start from DefaultSearchResultItems:

import type { PropsWithChildren } from "react";
import type { UserResponse } from "stream-chat";
import {
  DefaultSearchResultItems,
  SearchSourceResultList,
  WithComponents,
} from "stream-chat-react";

const InviteUserResult = ({ item }: { item: UserResponse }) => (
  <button className="invite-result" type="button">
    Invite {item.name ?? item.id}
  </button>
);

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

const overrides = { SearchSourceResultList: ResultList };

export const WithInviteResults = ({ children }: PropsWithChildren) => (
  <WithComponents overrides={overrides}>{children}</WithComponents>
);

A source of your own needs an entry under its type; see Searching your own data.

Data management

The data comes from the controller. Chat creates one with ChannelSearchSource, UserSearchSource and MessageSearchSource when the app doesn't pass searchController. To change what is searched, pass your own; Choosing what to search shows how, and Search sources explains the sources, their filters and their state.

The two search contexts hold:

Both hooks throw outside their component. Loading data hooks has their details.

Typing the context of MessageSearchSource

MessageSearchSource builds three filters, each with a filter builder of its own:

• messageSearchChannelFilterBuilder: which channels to search in;
• messageSearchFilterBuilder: which messages to return;
• channelQueryFilterBuilder: which channels of the results to load.

Each builder can carry a context of your own, and the source's type parameter names them, one key per builder: messageSearchChannelContext, messageSearchContext and channelQueryContext. The third constructor argument configures the builders under messageSearchChannel, messageSearch and channelQuery. This source can limit the results to pinned messages:

import { MessageSearchSource } from "stream-chat";

const messageSource = new MessageSearchSource<{
  messageSearchContext: { onlyPinned: boolean };
}>(client, undefined, {
  messageSearch: {
    initialContext: { onlyPinned: false },
    initialFilterConfig: {
      pinned: {
        enabled: true,
        generate: ({ onlyPinned }) =>
          onlyPinned ? { pinned: { $eq: true } } : null,
      },
    },
  },
});

// later, from a toggle in the results header
messageSource.messageSearchFilterBuilder.updateContext({ onlyPinned: true });

Each builder's context also holds what the source sets itself: searchQuery for the first two, and cids, the channels to load, for the third. The source keeps its built-in generators for the message text and the channels to load, and adds yours. The new context applies from the next query.