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

Value	Description	Type
`additionalFlatListProps`	Additional props provided to the underlying FlatList. Don't use `additionalFlatListProps` to access the FlatList ref, use `setFlatListRef` instead.	`object`
`channels`	Array of channels currently loaded within the `ChannelList` component.	`array`
`channelListInitialized`	A 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`
`error`	True if a call to query channels API call within `ChannelList` component results in error, either during first load or during pagination.	`Error object \| boolean`
`hasNextPage`	False if `ChannelList` has loaded all channels for the current filters.	`boolean`
`loadingChannels`	True if `ChannelList` component is loading the first page of channels.	`boolean`
`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. Defaults to `0.1`.	`number`
`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.	`boolean`
`loadNextPage`	Loads the next page for `ChannelList`.	`function`
`maxUnreadCount`	Max 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`
`mutedStatusPosition`	Position of the muted status component within the Preview. Defaults to `'inlineTitle'`.	`trailingBottom \| inlineTitle`
`pinnedStatusPosition`	Position of the pinned status component within the Preview. Defaults to `'inlineTitle'`.	`trailingBottom \| inlineTitle`
`swipeActionsEnabled`	If true, the user can swipe to perform actions on a channel. Defaults to `true`.	`boolean`
`numberOfSkeletons`	The number of Skeleton items to display in the LoadingIndicator. Defaults to `8`.	`number`
`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. Note: a `Channel` instance is not serializable and will therefore raise warnings if passed as a parameter through navigation to another screen.	`function`
`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.	`boolean`
`refreshList`	Function to manually re-sync or refresh the channels in `ChannelList` component. Calling `refreshList` will trigger a RefreshControl on underlying FlatList component.	`function`
`reloadList`	Manually reloads channels in `ChannelList`. Calling `reloadList` clears the current list and shows a loading indicator until new results arrive.	`function`
`setFlatListRef`	Callback 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)} />;