ChannelListView

ChannelListView renders the list of channels inside ChannelList. This is the default component for the List prop.

Best Practices

  • Keep list item rendering lightweight to preserve scroll performance.
  • Pass stable additionalFlatListProps and memoize callbacks.
  • Use loadMoreThreshold conservatively to avoid excessive pagination calls.
  • Show clear EmptyStateIndicator and LoadingErrorIndicator states.
  • Avoid modifying channels directly; use context setters like reloadList or refreshList.

Props

PropDescriptionType
additionalFlatListPropsAdditional props provided to the underlying FlatList. Don't use this to access the FlatList ref; use setFlatListRef instead. See example below.object
channelsArray of channels currently loaded within the ChannelList component.array
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
loadingChannelsTrue if ChannelList component is loading the first page of channels.boolean
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
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
loadNextPageLoads the next page for ChannelList.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. This value is attached to refreshing prop of underlying FlatList component of ChannelList.boolean
refreshListFunction to manually re-sync or refresh the channels in ChannelList component. Calling refreshList will trigger a RefreshControl on the 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. Receives a React ref (FlatList ref) as a parameter. See example below.function

Examples

additionalFlatListProps example

const flatListProps = { bounces: true };

<ChannelList additionalFlatListProps={flatListProps} />;

setFlatListRef example

const flatListRef = useRef();

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

UI Component Overrides

The UI components used by ChannelListView are read from ComponentsContext and can be customized via WithComponents. Wrap an ancestor with WithComponents and pass the components you want to override.

import { ChannelList, WithComponents } from "stream-chat-react-native";

<WithComponents
  overrides={{
    EmptyStateIndicator: CustomEmpty,
    LoadingIndicator: CustomLoading,
  }}
>
  <ChannelList filters={filters} sort={sort} />
</WithComponents>;

The following components can be overridden:

ComponentDescriptionTypeDefault
EmptyStateIndicatorRendered when the channel list is empty and not loading via the ListEmptyComponent prop on the FlatList.ComponentTypeEmptyStateIndicator
ChannelListFooterLoadingIndicatorRendered when loadingNextPage from ChannelsContext is true via the ListFooterComponent prop on the FlatList.ComponentTypeChannelListFooterLoadingIndicator
ListHeaderComponentRendered when provided if the channel list is not empty via the ListHeaderComponent prop on the FlatList.ComponentType-
LoadingErrorIndicatorRendered when error from ChannelsContext is true, and the channel list is empty and not loading.ComponentTypeLoadingErrorIndicator
LoadingIndicatorRendered when the channel list is empty and loading via the ListEmptyComponent prop on the FlatList.ComponentTypeChannelListLoadingIndicator
Previous
ChannelList
Next
ChannelsContext