ChannelsContext

ChannelsContext is provided by ChannelList. If you are not familiar with the React Context API, see the React docs.

Best Practices

• Use useChannelsContext for consistent access and typings.
• Treat channels as read-only; use context helpers to mutate list state.
• Use reloadList when filters change, and refreshList for pull-to-refresh.
• Check hasNextPage and loadingNextPage before triggering pagination.
• Keep list UI components lightweight to preserve scroll performance.

Basic Usage

Consume ChannelsContext in any child of ChannelList:

import { useContext } from "react";
import { ChannelsContext } from "stream-chat-react-native";

const { channels, reloadList } = useContext(ChannelsContext);

Alternatively, use the useChannelsContext hook.

import { useChannelsContext } from "stream-chat-react-native";

const { channels, reloadList } = useChannelsContext();

Value

additionalFlatListProps

Additional props provided to the underlying FlatList.

Example

const flatListProps = { bounces: true };

<ChannelList additionalFlatListProps={flatListProps} />;

channels

Array of channels currently loaded within the ChannelList component.

error

True if a call to query channels API call within ChannelList component results in error, either during first load or during pagination.

hasNextPage

False if ChannelList has loaded all channels for the current filters.

ListHeaderComponent

Rendered when provided if the channel list is not empty via the ListHeaderComponent prop on the FlatList.

loadingChannels

True if ChannelList component is loading the first page of channels.

loadMoreThreshold

Sets the onEndReachedThreshold of the underlying FlatList. We recommend using 0.1 as the default value for this prop, as changing it might hit additional channelQuery calls, and you might reach the limit.

loadingNextPage

True if ChannelList component is loading more channels as part of pagination. This will be set to true when user scrolls to bottom of the list and hasNextPage is true.

loadNextPage

Loads the next page for ChannelList.

maxUnreadCount

Max number to display within unread notification badge. The value cannot be higher than 255, which is the limit on backend side.

numberOfSkeletons

The number of Skeleton items to display in the LoadingIndicator.

onSelect

Function called when a user presses an item in the ChannelList. The function is called with the Channel instance corresponding to the list item as the only parameter. This callback is often used for navigating to a channel screen.

Example

onSelect={(channel) => { /** navigation logic */ }}

refreshing

True if ChannelList component is refreshing the list (using refreshList function call). Refreshing state will be triggered either when user executes pull-to-refresh gesture or if network connection is being recovered. This value is attached to refreshing prop of underlying FlatList component of ChannelList.

refreshList

Function to manually re-sync or refresh the channels in ChannelList component.

reloadList

Manually reloads channels in ChannelList.

setFlatListRef

Callback function to access the underlying FlatList ref.

Example

const flatListRef = useRef();

<ChannelList setFlatListRef={(ref) => (flatListRef.current = ref)} />;

EmptyStateIndicator

Rendered when the channel list is empty and not loading via the ListEmptyComponent prop on the FlatList.

FooterLoadingIndicator

Rendered when loadingNextPage from ChannelsContext is true via the ListFooterComponent prop on the FlatList.

HeaderErrorIndicator

Rendered when error from ChannelsContext is true.

HeaderNetworkDownIndicator

Rendered when isOnline from ChatContext is false.

LoadingErrorIndicator

Rendered when error from ChannelsContext is true, and the channel list is empty and not loading.

LoadingIndicator

Rendered when the channel list is empty and loading via the ListEmptyComponent prop on the FlatList.

Preview

List item rendered by the underlying FlatList.

PreviewAvatar

Avatar component rendered within Preview.

PreviewMessage

Message component rendered within Preview.

PreviewStatus

Status component rendered within Preview.

PreviewTitle

Title component rendered within Preview.

PreviewUnreadCount

Unread count component rendered within Preview.

Skeleton

Row item rendered in the LoadingIndicator.