Info:
This is release candidate documentation for Stream Chat React Native SDK v10. For the latest stable version, see the latest version (v9).

ChannelsContext

ChannelsContext holds what a ChannelList gives the components inside it: its ChannelPaginator, the configuration passed to it, and the functions that load and refresh it. ChannelList provides it; read it with useChannelsContext(). The paginator is explained on Channel list paginators.

Best practices

  • Read the loaded channels and the query state from paginator.state with useStateStore. The context holds the paginator, not its channels: it doesn't change when the list does.
  • Call useChannelsContext() only inside a ChannelList, such as in a row or an override the list renders. It throws anywhere else.
  • Outside the list, use the paginator you passed to it. It's the same object as paginator in the context.

Basic usage

This header counts the loaded channels. It's registered as the list's ListHeaderComponent, so it renders above the first row, inside the list:

src/ChannelListWithCount.tsx
import { Text } from "react-native";
import type {
  Channel,
  ChannelPaginator,
  ChannelPaginatorState,
} from "stream-chat";
import {
  ChannelList,
  useChannelsContext,
  useStateStore,
  WithComponents,
} from "stream-chat-react-native";
import type { ComponentOverrides } from "stream-chat-react-native";

const countSelector = ({ items }: ChannelPaginatorState) => ({
  count: items?.length ?? 0,
});

const LoadedCount = () => {
  const { paginator } = useChannelsContext();
  const { count } = useStateStore(paginator.state, countSelector);

  return <Text>{count} conversations loaded</Text>;
};

const overrides: ComponentOverrides = { ListHeaderComponent: LoadedCount };

export const ChannelListWithCount = ({
  onSelect,
  paginator,
}: {
  onSelect: (channel: Channel) => void;
  paginator: ChannelPaginator;
}) => (
  <WithComponents overrides={overrides}>
    <ChannelList onSelect={onSelect} paginator={paginator} />
  </WithComponents>
);

Values

Value Type Description
additionalFlatListProps Partial<FlatListProps<Channel>> The additionalFlatListProps prop, {} by default.
getChannelActionItems GetChannelActionItems | undefined The getChannelActionItems prop. The rows' swipe actions and options sheet read it.
loadMoreThreshold number The loadMoreThreshold prop, 0.1 by default.
loadNextPage () => Promise<void> Loads the next page with paginator.toTail(). Does nothing until the first page has loaded. The list calls it when the user scrolls near the end, while the paginator has more channels.
maxUnreadCount number The maxUnreadCount prop, 255 by default.
mutedStatusPosition 'trailingBottom' | 'inlineTitle' | undefined The mutedStatusPosition prop, 'inlineTitle' by default.
numberOfSkeletons number The numberOfSkeletons prop, 8 by default.
onSelect ((channel: Channel) => void) | undefined The onSelect prop. The default row calls it when it's tapped.
paginator ChannelPaginator The paginator passed to ChannelList.
pinnedStatusPosition 'trailingBottom' | 'inlineTitle' | undefined The pinnedStatusPosition prop, 'inlineTitle' by default.
refreshList () => void | Promise<void> Queries the first page again while the loaded channels stay on screen, as pull-to-refresh does. Ignored within 5 seconds of the last refresh, or of the list mounting, unless the last query failed.
reloadList () => Promise<void> Clears the channels and loads the first page again with paginator.reload(). The list shows its placeholder rows meanwhile.
setFlatListRef (ref: FlatList<Channel> | null) => void Passes the list's FlatList ref to the setFlatListRef prop, when it's set.
swipeActionsEnabled boolean | undefined The swipeActionsEnabled prop, true by default.

loadNextPage, refreshList, reloadList and setFlatListRef keep the same identity for the life of the list. The context value changes when one of the list's props does, so pass objects and functions to ChannelList with a stable identity.

Related hooks

  • useChannelsContext() returns the value above, and throws outside ChannelList.
  • useStateStore(paginator.state, selector) reads the paginator's items, isLoading, hasMoreTail and lastQueryError. See Loading data hooks.