# ChannelListView

> **Info:** This is release candidate documentation for **Stream Chat React Native SDK v10**. For the latest stable version, see the [latest version (v9)](https://getstream.io/chat/docs/sdk/react-native/).

`ChannelListView` is the `FlatList` of rows that [`ChannelList`](https://getstream.io/chat/docs/sdk/react-native/v10/component-reference/channel-list/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`](https://getstream.io/chat/docs/sdk/react-native/v10/component-reference/channel-list/channel-preview/).

`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](https://getstream.io/chat/docs/sdk/react-native/v10/component-reference/channel-list/channellist/#ui-customization), 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:

```tsx title="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](https://getstream.io/chat/docs/sdk/react-native/v10/ui-cookbook/channel-list/channel-list-background/) 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`.

## Related hooks

- `useChannelsContext()` returns the context `ChannelListView` reads. See [ChannelsContext](https://getstream.io/chat/docs/sdk/react-native/v10/component-reference/channel-list/channelscontext/).
- `useNetworkConnectionState()` and `useSettledWSConnectionHealth()` give the connection state behind the network banner. See [Connection hooks](https://getstream.io/chat/docs/sdk/react-native/v10/reference/hooks/connection-hooks/).

---

For the most recent version of this documentation, visit [https://getstream.io/chat/docs/sdk/react-native/v10/component-reference/channel-list/channel-list-view/](https://getstream.io/chat/docs/sdk/react-native/v10/component-reference/channel-list/channel-list-view/).