ChannelListView

ChannelListView is the FlatList of rows that ChannelList renders. ChannelList reads the paginator's state and passes it down as props, and ChannelListView turns it into rows, placeholders, an empty state, an error state and the banners over the list. Each row is a ChannelPreview.

ChannelListView has no override key: ChannelList always renders it. Change what it shows through the keys it reads, its props on ChannelList, and the theme.

Best practices

Change the list's parts with the override keys listed on ChannelList, and the FlatList with additionalFlatListProps on ChannelList.
Keep additionalFlatListProps stable. It's spread on the FlatList after the props the view sets, so it replaces them, data and renderItem included.
Render ChannelListView only inside ChannelList, or inside a ChannelsProvider of your own. It reads ChannelsContext, and throws without it.

Basic usage

The list's style comes from the theme's channelListView keys, flatList for the list and flatListContent for its content container:

App.tsx

import type { PropsWithChildren } from "react";
import type { StreamChat } from "stream-chat";
import { Chat, OverlayProvider } from "stream-chat-react-native";
import type { DeepPartial, Theme } from "stream-chat-react-native";

// Declared once, at module scope.
const theme: DeepPartial<Theme> = {
  channelListView: {
    flatList: { backgroundColor: "#f4f6fb" },
    flatListContent: { paddingBottom: 24 },
  },
};
const overlayValue = { style: theme };

export const ChatRoot = ({
  children,
  client,
}: PropsWithChildren<{ client: StreamChat }>) => (
  <OverlayProvider value={overlayValue}>
    <Chat client={client} style={theme}>
      {children}
    </Chat>
  </OverlayProvider>
);

The Channel backgrounds UI cookbook builds on this.

What it renders

State	What renders
`error` is set, the list isn't refreshing or loading, and the first page hasn't loaded	`LoadingErrorIndicator` in place of the list. Its `retry` calls `reloadList`.
`loadingChannels`	`ChannelListLoadingIndicator`, as the `FlatList`'s empty component
`channels` is empty	`EmptyStateIndicator` with `listType: 'channel'`
`loadingNextPage`	`ChannelListFooterLoadingIndicator` after the last row
The network is offline, or the WebSocket is down	`ChannelListHeaderNetworkDownIndicator` over the top of the list
`error` is set while channels are on screen	`ChannelListHeaderErrorIndicator` over the top of the list. Pressing it calls `refreshList`.

The banners don't show while the first page is loading, and the network banner takes precedence over the error banner. The FlatList uses channel.cid as each row's key, calls loadNextPage from onEndReached while hasNextPage is true, and calls refreshList on pull-to-refresh.

Props

ChannelList passes the first group of props. The second group defaults to the values in ChannelsContext, except the inert props that have no default, so a prop you pass replaces the context's.

Prop	Type	Default	Description
`channelListInitialized`	`boolean`	required	Whether the paginator has loaded its first page. The error state replaces the list only while it's `false` or `channels` is `null`.
`channels`	`Channel[] \| null`	required	The channels to render, after `channelRenderFilterFn`.
`error`	`Error`		The paginator's `lastQueryError`.
`hasNextPage`	`boolean`	required	Whether the paginator has more channels to load. `loadNextPage` is called only while it's `true`.
`loadingChannels`	`boolean`	required	Whether the first page is loading: `true` while the paginator has no channels and no error.
`loadingNextPage`	`boolean`	required	Whether the next page is loading.
`refreshing`	`boolean`	required	Whether a pull-to-refresh is running. Passed to the `FlatList`'s `refreshing`.
`additionalFlatListProps`	`Partial<FlatListProps<Channel>>`	from `ChannelsContext`	Props spread on the `FlatList` after the ones the view sets.
`loadMoreThreshold`	`number`	from `ChannelsContext`	The `FlatList`'s `onEndReachedThreshold`.
`loadNextPage`	`() => Promise<void>`	from `ChannelsContext`	Loads the next page.
`refreshList`	`() => void \| Promise<void>`	from `ChannelsContext`	Refreshes the first page, on pull-to-refresh and from the error banner.
`reloadList`	`() => Promise<void>`	from `ChannelsContext`	Reloads the list from scratch, from the error state.
`setFlatListRef`	`(ref: FlatList<Channel> \| null) => void`	from `ChannelsContext`	Receives the `FlatList` ref.
`getChannelActionItems`	`GetChannelActionItems`		Inert. The view doesn't read it; the rows read it from `ChannelsContext`.
`mutedStatusPosition`	`'trailingBottom' \| 'inlineTitle'`		Inert. The view doesn't read it; the rows read it from `ChannelsContext`.
`pinnedStatusPosition`	`'trailingBottom' \| 'inlineTitle'`		Inert. The view doesn't read it; the rows read it from `ChannelsContext`.
`swipeActionsEnabled`	`boolean`		Inert. The view doesn't read it; the rows read it from `ChannelsContext`.

The first group is exported as the type ChannelListState.

useChannelsContext() returns the context ChannelListView reads. See ChannelsContext.
useNetworkConnectionState() and useSettledWSConnectionHealth() give the connection state behind the network banner. See Connection hooks.

ChannelListView

Best practices

Basic usage

What it renders

Props

Related hooks