# ChannelListView

`ChannelListView` renders the list of channels inside [`ChannelList`](/chat/docs/sdk/react-native/v9/core-components/channel-list/). This is the default component for the [`List`](/chat/docs/sdk/react-native/v9/core-components/channel-list#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

### `additionalFlatListProps`

Additional props provided to the underlying [FlatList](https://reactnative.dev/docs/flatlist#props).

#### Example

```tsx
const flatListProps = { bounces: true };

<ChannelList additionalFlatListProps={flatListProps} />;
```

<admonition type="warning">

Don't use `additionalFlatListProps` to access the FlatList ref, use `setFlatListRef` instead.

</admonition>

| Type   |
| ------ |
| Object |

### `channels`

Array of channels currently loaded within the `ChannelList` component.

| Type  |
| ----- |
| Array |

### `error`

True if a call to [query channels API call](/chat/docs/javascript/query_channels/) within `ChannelList` component results in error, either during first load or during pagination.

| Type                        |
| --------------------------- |
| `Error Object` \| `Boolean` |

### `loadingChannels`

True if `ChannelList` component is loading the first page of channels.

| Type    |
| ------- |
| Boolean |

### `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`](/chat/docs/sdk/react-native/v9/contexts/channels-context#hasnextpage/) is true.

| Type    |
| ------- |
| Boolean |

### `loadMoreThreshold`

Sets the [`onEndReachedThreshold`](https://reactnative.dev/docs/flatlist#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.

| Type   | Default |
| ------ | ------- |
| Number | 0.1     |

### `loadNextPage`

Loads the next page for `ChannelList`.

| Type     |
| -------- |
| Function |

### `refreshing`

True if `ChannelList` component is refreshing the list (using [`refreshList`](#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](https://reactnative.dev/docs/flatlist#refreshing) prop of underlying `FlatList` component of `ChannelList`.

| Type    |
| ------- |
| Boolean |

### `refreshList`

Function to manually re-sync or refresh the channels in `ChannelList` component.

<admonition type="note">

Calling `refreshList` will trigger a [RefreshControl](https://reactnative.dev/docs/refreshcontrol) on underlying FlatList component.

</admonition>

| Type     |
| -------- |
| Function |

### `reloadList`

Manually reloads channels in `ChannelList`.

<admonition type="note">

Calling `reloadList` clears the current list and shows a loading indicator until new results arrive.

</admonition>

| Type     |
| -------- |
| Function |

### `setFlatListRef`

Callback function to access the underlying [FlatList](https://reactnative.dev/docs/flatlist) ref.

#### Example

```tsx
const flatListRef = useRef();

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

| Type     |
| -------- |
| Function |

| Parameter                                                                                   | Description  |
| ------------------------------------------------------------------------------------------- | ------------ |
| [`React ref`](https://reactjs.org/docs/refs-and-the-dom.html#adding-a-ref-to-a-dom-element) | FlatList ref |

## UI Component Props

### `EmptyStateIndicator`

Rendered when the channel list is empty and not loading via the [ListEmptyComponent](https://reactnative.dev/docs/flatlist#listemptycomponent) prop on the FlatList.

| Type          | Default                                                                                                                                            |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| ComponentType | [`EmptyStateIndicator`](https://github.com/GetStream/stream-chat-react-native/blob/main/package/src/components/Indicators/EmptyStateIndicator.tsx) |

### `FooterLoadingIndicator`

Rendered when [`loadingNextPage` from `ChannelsContext`](/chat/docs/sdk/react-native/v9/contexts/channels-context#loadingnextpage/) is true via the [`ListFooterComponent`](https://reactnative.dev/docs/flatlist#listfootercomponent) prop on the FlatList.

| Type            | Default                                                                                                                                                                         |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ComponentType` | [`ChannelListFooterLoadingIndicator`](https://github.com/GetStream/stream-chat-react-native/blob/main/package/src/components/ChannelList/ChannelListFooterLoadingIndicator.tsx) |

### `ListHeaderComponent`

Rendered when provided if the channel list is not empty via the [`ListHeaderComponent`](https://reactnative.dev/docs/flatlist#listheadercomponent) prop on the FlatList.

| Type          |
| ------------- |
| ComponentType |

### `LoadingErrorIndicator`

Rendered when [`error` from `ChannelsContext`](/chat/docs/sdk/react-native/v9/contexts/channels-context#error/) is true, and the channel list is empty and not loading.

| Type          | Default                                                                                                                                                |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ComponentType | [`LoadingErrorIndicator`](https://github.com/GetStream/stream-chat-react-native/blob/main/package/src/components/Indicators/LoadingErrorIndicator.tsx) |

### `LoadingIndicator`

Rendered when the channel list is empty and loading via the [ListEmptyComponent](https://reactnative.dev/docs/flatlist#listemptycomponent) prop on the FlatList.

| Type          | Default                                                                                                                                                             |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ComponentType | [`ChannelListLoadingIndicator`](https://github.com/GetStream/stream-chat-react-native/blob/main/package/src/components/ChannelList/ChannelListLoadingIndicator.tsx) |


---

This page was last updated at 2026-04-03T17:24:33.434Z.

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