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();

Values

ValueDescriptionType
additionalFlatListPropsAdditional props provided to the underlying FlatList. Don't use additionalFlatListProps to access the FlatList ref, use setFlatListRef instead.object
channelsArray of channels currently loaded within the ChannelList component.array
channelListInitializedA control prop used to determine whether the first query of the channel list has succeeded. Don't set this prop manually, it is set automatically by the ChannelList component.boolean
errorTrue if a call to query channels API call within ChannelList component results in error, either during first load or during pagination.Error object | boolean
hasNextPageFalse if ChannelList has loaded all channels for the current filters.boolean
loadingChannelsTrue if ChannelList component is loading the first page of channels.boolean
loadMoreThresholdSets 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. Defaults to 0.1.number
loadingNextPageTrue 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.boolean
loadNextPageLoads the next page for ChannelList.function
maxUnreadCountMax number to display within unread notification badge. The value cannot be higher than 255, which is the limit on backend side. Defaults to 255.number
mutedStatusPositionPosition of the muted status component within the Preview. Defaults to 'inlineTitle'.trailingBottom | inlineTitle
swipeActionsEnabledIf true, the user can swipe to perform actions on a channel. Defaults to true.boolean
numberOfSkeletonsThe number of Skeleton items to display in the LoadingIndicator. Defaults to 6.number
onSelectFunction 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. Note: a Channel instance is not serializable and will therefore raise warnings if passed as a parameter through navigation to another screen.function
refreshingTrue 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.boolean
refreshListFunction to manually re-sync or refresh the channels in ChannelList component. Calling refreshList will trigger a RefreshControl on underlying FlatList component.function
reloadListManually reloads channels in ChannelList. Calling reloadList clears the current list and shows a loading indicator until new results arrive.function
setFlatListRefCallback function to access the underlying FlatList ref.function

Examples

additionalFlatListProps

const flatListProps = { bounces: true };

<ChannelList additionalFlatListProps={flatListProps} />;

onSelect

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

setFlatListRef

const flatListRef = useRef();

<ChannelList setFlatListRef={(ref) => (flatListRef.current = ref)} />;
Previous
ChannelListView
Next
ChannelAvatar