# ChannelList

The `ChannelList` displays a list of channels using React Native's [FlatList](https://reactnative.dev/docs/flatlist) component.
`ChannelList` internally fetches a list of channels using the [client's query channels function](/chat/docs/javascript/query-channels/); to which you can pass the [`filters`](#filters), [`sort`](#sort) and [`options`](#options) parameters via props on `ChannelList`.

When a user presses on a channel in the list you can provide navigation logic via the [`onSelect`](#onselect) prop to navigate to the selected channel.

## Basic Usage

`ChannelList` should be rendered inside of the `OverlayProvider` and `Chat` so it is provided the appropriate contexts to function internally.

```tsx {5-7,12-17}
import { StreamChat } from 'stream-chat';
import { ChannelList, Chat, OverlayProvider } from 'stream-chat-react-native';

const client = StreamChat.getInstance('api_key');
const filters = { members: { $in: [ 'vishal', 'lucas', 'neil' ] } };
const sort = { last_updated: -1 };
const options = { limit: 20, messages_limit: 30 };

export const App = () =>
  <OverlayProvider>
    <Chat client={client}>
      <ChannelList
        filters={filters}
        sort={sort}
        options={options}
        onSelect={(channel) => /** navigate to channel screen */ }
      />
    </Chat>
  </OverlayProvider>;
```

## Context Providers

`ChannelList` contains the provider for the `ChannelsContext`.
This can be accessed using the corresponding hook.

| Context           | Hook                 |
| ----------------- | -------------------- |
| `ChannelsContext` | `useChannelsContext` |

## UI Customizations

The `ChannelList` is highly customizable.
The UI can be tailored to your design by replacing any number of components with custom components.

Customizing the title can be done easily by providing a custom component to the appropriate prop.

```tsx
const CustomPreviewTitle = ({ channel }) => (
  <Text>
    {channel.data.customProperty} - {channel.data.name}
  </Text>
);

<ChannelList PreviewTitle={CustomPreviewTitle} />;
```

<tabs>

<tabs-item value="list-item-components" label="List Items">

![](@chat-sdk/react-native/v4/_assets/api-references/components/channel-list/visual_guide_1.png)

</tabs-item>

<tabs-item value="indicators" label="Indicators">

![](@chat-sdk/react-native/v4/_assets/api-references/components/channel-list/visual_guide_2.png)

</tabs-item>

</tabs>

## Props

### **filters**

Filter object passed internally to the [client query function](/chat/docs/javascript/query-channels/) as a parameter.
You can filter a query on [built-in](/chat/docs/javascript/query-channels/#common-filters-by-use-case/) and custom fields on a Channel.

#### Example

Filter to query channels which users `vishal` or `jaap` are members of.

```tsx
const filter = {
  type: "messaging",
  members: {
    $in: ["vishal", "jaap"],
  },
};
```

<admonition type="note">

For optimal performance you should pass a filter object with a static reference.
You can use a filter object that is not created inline; or memoize an inline filter object before passing it to the `ChannelList` to achieve this.

</admonition>

| Type   |
| ------ |
| object |


### **sort**

Sort object passed internally to the [client query function](/chat/docs/javascript/query-channels/) as a parameter.
You can sort a query on [built-in](/chat/docs/javascript/query-channels/#query-parameters/) and custom fields on a Channel.

#### Example

```tsx
const sort = { last_updated: -1 };
```

<admonition type="note">

For optimal performance you should pass a sort object with a static reference.
You can use a sort object that is not created inline; or memoize an inline sort object before passing it to the `ChannelList` to achieve this.

</admonition>

| Type   |
| ------ |
| object |


### **options**

[Options object](/chat/docs/javascript/query-channels/#query-options/) passed internally to the [client query function](/chat/docs/javascript/query-channels/) as a parameter.

#### Example

```tsx
const options = { message_limit: 100 };
```

<admonition type="note">

Unlike the [filters](#filters) or [sort](#sort) objects, changing the options object alone will not re-query the list of channels.

</admonition>

| Type   |
| ------ |
| object |


### **onSelect**

Function called when a user presses an item in the `ChannelList`.
The function is called with the [`Channel` instance](/chat/docs/javascript/creating-channels/) corresponding to the list item as the only parameter.
This callback is often used for navigating to a channel screen.

#### Example

```tsx
onSelect={(channel) => { /** navigation logic */ }}
```

<admonition type="note">

A `Channel` instance is not serializable and will therefore raise warnings if passed as a parameter through navigation to another screen.

</admonition>

| Type     |
| -------- |
| function |

| Parameter | Description        |
| --------- | ------------------ |
| channel   | `Channel` instance |


### 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 |


### loadMoreThreshold

Sets the [`onEndReachedThreshold`](https://reactnative.dev/docs/flatlist#onendreachedthreshold) of the underlying FlatList.

| Type   | Default |
| ------ | ------- |
| number | 2       |


### lockChannelOrder

Locks the order of the channels in the list so they will not dynamically reorder by most recent message when a new message is received.

| Type    | Default |
| ------- | ------- |
| boolean | false   |


### maxUnreadCount

Max number to display within unread notification badge. The value cannot be higher than 255, which is the limit on backend side.

| Type   | Default |
| ------ | ------- |
| number | 255     |


### numberOfSkeletons

The number of [`Skeleton`](#skeleton) items to display in the [`LoadingIndicator`](#loadingindicator).

| Type   | Default |
| ------ | ------- |
| number | 6       |


### onAddedToChannel

Override for [Event Listener](#event-listeners) behavior when the user is added to a channel.
The default behavior adds the channel to the list.

| Type     |
| -------- |
| function |

| Parameter   | Description                                                                                                   |
| ----------- | ------------------------------------------------------------------------------------------------------------- |
| setChannels | Setter function for the internal `channels` state                                                             |
| event       | [Event object](/chat/docs/react/event-object/#event-object/) corresponding to `notification.added_to_channel` |


### onChannelDeleted

Override for [Event Listener](#event-listeners) behavior when a channel is deleted.
The default behavior removes the channel from the list.

| Type     |
| -------- |
| function |

| Parameter   | Description                                                                                     |
| ----------- | ----------------------------------------------------------------------------------------------- |
| setChannels | Setter function for the internal `channels` state                                               |
| event       | [Event object](/chat/docs/react/event-object/#event-object/) corresponding to `channel.deleted` |


### onChannelHidden

Override for [Event Listener](#event-listeners) behavior when a channel is hidden.
The default behavior removes the channel from the list.

| Type     |
| -------- |
| function |

| Parameter   | Description                                                                                    |
| ----------- | ---------------------------------------------------------------------------------------------- |
| setChannels | Setter function for the internal `channels` state                                              |
| event       | [Event object](/chat/docs/react/event-object/#event-object/) corresponding to `channel.hidden` |


### onChannelVisible

Override for [Event Listener](#event-listeners) behavior when a channel is made visible.
The default behavior adds the channel to the list.

| Type     |
| -------- |
| function |

| Parameter   | Description                                                                                     |
| ----------- | ----------------------------------------------------------------------------------------------- |
| setChannels | Setter function for the internal `channels` state                                               |
| event       | [Event object](/chat/docs/react/event-object/#event-object/) corresponding to `channel.visible` |


### onChannelTruncated

Override for [Event Listener](#event-listeners) behavior when a channel is truncated.
The default behavior reloads the list.

| Type     |
| -------- |
| function |

| Parameter   | Description                                                                                       |
| ----------- | ------------------------------------------------------------------------------------------------- |
| setChannels | Setter function for the internal `channels` state                                                 |
| event       | [Event object](/chat/docs/react/event-object/#event-object/) corresponding to `channel.truncated` |


### onChannelUpdated

Override for [Event Listener](#event-listeners) behavior when a channel is updated.
The default behavior updates the `data` on a channel with that from the event.

| Type     |
| -------- |
| function |

| Parameter   | Description                                                                                     |
| ----------- | ----------------------------------------------------------------------------------------------- |
| setChannels | Setter function for the internal `channels` state                                               |
| event       | [Event object](/chat/docs/react/event-object/#event-object/) corresponding to `channel.updated` |


### onMessageNew

Override for [Event Listener](#event-listeners) behavior when a message is received on a channel that is not being watched.
The default behavior adds the channel to the list.

| Type     |
| -------- |
| function |

| Parameter   | Description                                                                                              |
| ----------- | -------------------------------------------------------------------------------------------------------- |
| setChannels | Setter function for the internal `channels` state                                                        |
| event       | [Event object](/chat/docs/react/event-object/#event-object/) corresponding to `notification.message_new` |


### onRemovedFromChannel

Override for [Event Listener](#event-listeners) behavior when the user is removed from a channel.
The default behavior removes the channel from the list.

| Type     |
| -------- |
| function |

| Parameter   | Description                                                                                                       |
| ----------- | ----------------------------------------------------------------------------------------------------------------- |
| setChannels | Setter function for the internal `channels` state                                                                 |
| event       | [Event object](/chat/docs/react/event-object/#event-object/) corresponding to `notification.removed_from_channel` |


### 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  |
| --------- | ------------ |
| ref       | FlatList ref |


### 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                                                                                                                                          |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| component | [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/v3/contexts/channels-context#loadingnextpage/) is true via the [`ListFooterComponent`](https://reactnative.dev/docs/flatlist#listfootercomponent) prop on the FlatList.

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


### HeaderErrorIndicator

Rendered when [`error` from `ChannelsContext`](/chat/docs/sdk/react-native/v3/contexts/channels-context#error/) is true.

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


### HeaderNetworkDownIndicator

Rendered when [`isOnline` from `ChatContext`](/chat/docs/sdk/react-native/v3/contexts/chat-context#isonline/) is false.

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


### List

Component to render the list of channels.

| Type      | Default                                                                                        |
| --------- | ---------------------------------------------------------------------------------------------- |
| component | [`ChannelListMessenger`](/chat/docs/sdk/react-native/v3/ui-components/channel-list-messenger/) |


### 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      |
| --------- |
| component |


### LoadingErrorIndicator

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

| Type      | Default                                                                                                                                              |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| component | [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                                                                                                                                                           |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| component | [ChannelListLoadingIndicator](https://github.com/GetStream/stream-chat-react-native/blob/main/package/src/components/ChannelList/ChannelListLoadingIndicator.tsx) |


### Preview

List item rendered by the underlying [FlatList](https://reactnative.dev/docs/flatlist#required-renderitem).

| Type      | Default                                                                                            |
| --------- | -------------------------------------------------------------------------------------------------- |
| component | [ChannelPreviewMessenger](/chat/docs/sdk/react-native/v3/ui-components/channel-preview-messenger/) |


### PreviewAvatar

Avatar component rendered within [`Preview`](/chat/docs/sdk/react-native/v3/ui-components/channel-preview-messenger/).

| Type      | Default                                                                       |
| --------- | ----------------------------------------------------------------------------- |
| component | [ChannelAvatar](/chat/docs/sdk/react-native/v3/ui-components/channel-avatar/) |


### PreviewMessage

Message component rendered within [`Preview`](/chat/docs/sdk/react-native/v3/ui-components/channel-preview-messenger/).

| Type      | Default                                                                                        |
| --------- | ---------------------------------------------------------------------------------------------- |
| component | [ChannelPreviewMessage](/chat/docs/sdk/react-native/v3/ui-components/channel-preview-message/) |


### PreviewStatus

Status component rendered within [`Preview`](/chat/docs/sdk/react-native/v3/ui-components/channel-preview-messenger/).

| Type      | Default                                                                                      |
| --------- | -------------------------------------------------------------------------------------------- |
| component | [ChannelPreviewStatus](/chat/docs/sdk/react-native/v3/ui-components/channel-preview-status/) |


### PreviewTitle

Title component rendered within [`Preview`](/chat/docs/sdk/react-native/v3/ui-components/channel-preview-messenger/).

| Type      | Default                                                                                    |
| --------- | ------------------------------------------------------------------------------------------ |
| component | [ChannelPreviewTitle](/chat/docs/sdk/react-native/v3/ui-components/channel-preview-title/) |


### PreviewUnreadCount

Unread count component rendered within [`Preview`](/chat/docs/sdk/react-native/v3/ui-components/channel-preview-messenger/).

| Type      | Default                                                                                                 |
| --------- | ------------------------------------------------------------------------------------------------------- |
| component | [ChannelPreviewUnreadCount](/chat/docs/sdk/react-native/v3/ui-components/channel-preview-unread-count/) |


### Skeleton

Row item rendered in the [`LoadingIndicator`](#loadingindicator).

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



---

This page was last updated at 2026-07-10T16:05:05.367Z.

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