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

<admonition type="note">

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.

</admonition>

## General Usage

The `ChannelList` can be used to display the all the participants in the form of [FlatList](https://reactnative.dev/docs/flatlist).

> Note: The component should be defined within the `OverlayProvider` and `Chat` wrappers so that all the [contexts](https://www.notion.so/Contexts-6bdf5dd1346e433db4407131018b05b5?pvs=21) are provided to the component internally.

```jsx {11,12,13,14,15,16}
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>;
```

<admonition type="note">

When receiving channel information from channel events, the filters are not respected; the reason for this is that channel filters can get very complex, and implementing that filtering logic that supports all of the custom filter would be very hard to do. Implementing this on the backend side isn't an option as it is inefficient and has to cater to different filters. So, to help you with it, you will have to override the `notification.message_new` event using the [`onNewMessageNotification`](/chat/docs/sdk/react-native/core-components/channel-list#onnewmessagenotification/) and `message.new` event handlers using the [`onNewMessage`](/chat/docs/sdk/react-native/core-components/channel-list#onnewmessage/) prop of the `ChannelList` component.

</admonition>

## Context Providers

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

| Context                                                                                                                                          | Hook               |
| ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------ |
| [`ChannelsContext`](https://github.com/GetStream/stream-chat-react-native/blob/develop/package/src/contexts/channelsContext/ChannelsContext.tsx) | useChannelsContext |

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

<admonition type="info">

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.

<admonition type="info">

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.

<admonition type="info">

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.

<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               |
| ------------------ |
| `(channel) ⇒ void` |

### `additionalFlatListProps`

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

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

### `loadMoreThreshold`

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

### `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 the default Event Listener 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                            |
| options     | [ChannelListEventListenerOptions](/chat/docs/sdk/react-native/core-components/channel-list#channel-list-event-listener-options) object |

### `onChannelDeleted`

Override for the default Event Listener 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 the default Event Listener 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.deleted |

### `onChannelMemberUpdated`

Override for the default Event Listener behavior when a channel member is updated i.e., `member.updated` event is received. This is essential for channel pinning and archiving to work.

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

| Parameter        | Description                                                                                                                             |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| 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. |
| setChannels      | Setter function for the internal channels state.                                                                                        |
| event            | [Event Object](/chat/docs/react/event_object/#event-object/) corresponding to message.new.                                              |
| options          | [ChannelListEventListenerOptions](/chat/docs/sdk/react-native/core-components/channel-list#channel-list-event-listener-options) object  |

### `onChannelVisible`

Override for the default Event Listener 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.deleted |

### `onChannelTruncated`

Override for the default Event Listener 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.deleted |

### `onChannelUpdated`

Override for the default Event Listener 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.deleted |

### `onNewMessageNotification`

Override for the default Event Listener 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 channel.deleted                                          |
| options     | [ChannelListEventListenerOptions](/chat/docs/sdk/react-native/core-components/channel-list#channel-list-event-listener-options) object |

### `onNewMessage`

Override for the default Event Listener behavior when a message is received on a channel that is being watched. The default behavior moves the channel to the top of the list.

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

| Parameter        | Description                                                                                                                             |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| 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. |
| setChannels      | Setter function for the internal channels state.                                                                                        |
| event            | [Event Object](/chat/docs/react/event_object/#event-object/) corresponding to message.new.                                              |
| options          | [ChannelListEventListenerOptions](/chat/docs/sdk/react-native/core-components/channel-list#channel-list-event-listener-options) object  |

### `onRemovedFromChannel`

Override for the default Event Listener 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 channel.deleted. |

### `setFlatlistRef`

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

| Type           |
| -------------- |
| `(ref) ⇒ void` |

### `queryChannelsOverride`

A function that overrides the default `ChannelManager`'s `queryChannels` method, which is `StreamChat.queryChannels`.
It is particularly useful whenever we want to pass specific `cid`s that we want to query but also want to
paginate over them (which is not possible through normal `filters`). It comes with with several rules/assumptions:

- `StreamChat.queryChannels` has to be called inside of `queryChannelsOverride` (as it updates important `StreamChat` state)
- The return type has to be `Channel[]` (which is the return type of `StreamChat.queryChannels`)
- The `limit` and `offset` properties need to still be respected (where applicable) so that the underlying `ChannelManager` knows how to paginate properly under the hood

| Type                       |
| -------------------------- |
| `QueryChannelsRequestType` |

<admonition type="note">

This prop is available since version `8.2.0`.

The `filters` and `sort` properties passed to `ChannelList` are expected to still be stable and memoized; in other words, do not change `filters` in order to pass a different set of `cid`s but rather let the `queryChannelsOverride` implementation handle that internally (based on the pagination parameters the `ChannelManager` calculates internally).

</admonition>

Provided below is an example of what the override might look like:

```ts
const cids = Array.from({ length: 25 }, (_, i) => (i + 1).toString());

const queryChannelsOverride = (filters, sort, options, ...restParams) => {
  const { limit, offset } = options;

  const cidWindow = cids.slice(offset, offset + limit);
  const newFilters = { ...filters, cid: { $in: cidWindow } };

  return chatClient.queryChannels(newFilters, sort, options, ...restParams);
};
```

Given the following `ChannelList` configuration:

```tsx
// ... rest of the component
const filters = useMemo(() => ({}), []);
const options = useMemo(() => ({ offset: 0, limit: 10 }));
return <ChannelList filters={stableFilters} options={options} />;
```

the loading of the pages would work as follows:

1. On the first page, 10 items will be loaded, which will be the first 10 `cid`s
2. On the second page, `queryChannelsOverride` will be invoked with `offset: 10` and `limit: 10`, so `cid`s `10` through `19` will be loaded
3. On the last page, `queryChannelsOverride` will be invoked with `offset: 10` and `limit: 10`, and so our implementation will return the last 5 `cid`s (and the `ChannelManager` will at this point determine there are no pages left)

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

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

### `FooterLoadingIndicator`

Rendered when [`loadingNextPage` from `ChannelsContext`](https://github.com/GetStream/stream-chat-react-native/blob/develop/package/src/contexts/channelsContext/ChannelsContext.tsx/#loadingnextpage) is true via the [`ListFooterComponent`](https://reactnative.dev/docs/flatlist#listfootercomponent) prop on the [`FlatList`](https://reactnative.dev/docs/flatlist).

| Type          | Default Value                                                                                                                                                                                  |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ComponentType | `undefined` \| [`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/contexts/channels-context/#error/) is true.

| Type          | Default                                                                                                                                                                                    |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ComponentType | `undefined` \| [`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/contexts/chat-context/#isonline/) is false.

| Type          | Default                                                                                                                                                                                                |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ComponentType | `undefined` \| [`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                                                                                                                                                                 |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ComponentType | `undefined` \| [`ChannelListMessenger`](https://github.com/GetStream/stream-chat-react-native/blob/develop/package/src/components/ChannelList/ChannelListMessenger.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`](https://reactnative.dev/docs/flatlist).

| Type                          |
| ----------------------------- |
| `ComponentType` \|`undefined` |

### `LoadingErrorIndicator`

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

| Type          | Default                                                                                                                                                               |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ComponentType | `undefined` \| [`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](https://reactnative.dev/docs/flatlist).

| Type          | Default                                                                                                                                                                            |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ComponentType | `undefined` \| [`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).

| Type          | Default                                                                                                                                                                          |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ComponentType | `undefined` \| [`ChannelPreviewMessenger`](https://github.com/GetStream/stream-chat-react-native/blob/develop/package/src/components/ChannelPreview/ChannelPreviewMessenger.tsx) |

### `PreviewAvatar`

Avatar component rendered within [`Preview`](#preview).

| Type          | Default                                                                                                                                                      |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ComponentType | `undefined` \| [`ChannelAvatar`](https://github.com/GetStream/stream-chat-react-native/blob/develop/package/src/components/ChannelPreview/ChannelAvatar.tsx) |

### **`PreviewMessage`**

Message component rendered within [`Preview`](#preview).

| Type          | Default                                                                                                                                                                      |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ComponentType | `undefined` \| [`ChannelPreviewMessage`](https://github.com/GetStream/stream-chat-react-native/blob/develop/package/src/components/ChannelPreview/ChannelPreviewMessage.tsx) |

### `PreviewMutedStatus`

Channel muted status component rendered within [`Preview`](#preview).

| Type          | Default                                                                                                                                                                              |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ComponentType | `undefined` \| [`ChannelPreviewMutedStatus`](https://github.com/GetStream/stream-chat-react-native/blob/develop/package/src/components/ChannelPreview/ChannelPreviewMutedStatus.tsx) |

### `PreviewStatus`

Status component rendered within [`Preview`](#preview).

| Type          | Default                                                                                                                                                                    |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ComponentType | `undefined` \| [`ChannelPreviewStatus`](https://github.com/GetStream/stream-chat-react-native/blob/develop/package/src/components/ChannelPreview/ChannelPreviewStatus.tsx) |

### `PreviewTitle`

Title component rendered within [`Preview`](#preview).

| Type          | Default                                                                                                                                                                  |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ComponentType | `undefined` \| [`ChannelPreviewTitle`](https://github.com/GetStream/stream-chat-react-native/blob/develop/package/src/components/ChannelPreview/ChannelPreviewTitle.tsx) |

### `PreviewUnreadCount`

Unread count component rendered within [`Preview`](#preview).

| Type          | Default                                                                                                                                                                              |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ComponentType | `undefined` \| [`ChannelPreviewUnreadCount`](https://github.com/GetStream/stream-chat-react-native/blob/develop/package/src/components/ChannelPreview/ChannelPreviewUnreadCount.tsx) |

### `Skeleton`

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

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

## Channel List Event Listener Options

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

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

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

---

This page was last updated at 2025-08-15T14:16:28.889Z.

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