# 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/v3/_assets/api-references/components/channel-list/visual_guide_1.png)

</tabs-item>

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

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

</tabs-item>

</tabs>

## Props

### **filters**

<partial id="chat-sdk/react-native/v3/_partials/common-content/core-components/channel-list/props/filters"></partial>

### **sort**

<partial id="chat-sdk/react-native/v3/_partials/common-content/core-components/channel-list/props/sort"></partial>

### **options**

<partial id="chat-sdk/react-native/v3/_partials/common-content/core-components/channel-list/props/options"></partial>

### **onSelect**

<partial id="chat-sdk/react-native/v3/_partials/common-content/core-components/channel-list/props/on_select"></partial>

### additionalFlatListProps

<partial id="chat-sdk/react-native/v3/_partials/common-content/core-components/channel-list/props/additional_flat_list_props"></partial>

### loadMoreThreshold

<partial id="chat-sdk/react-native/v3/_partials/common-content/core-components/channel-list/props/load_more_threshold"></partial>

### lockChannelOrder

<partial id="chat-sdk/react-native/v3/_partials/common-content/core-components/channel-list/props/lock_channel_order"></partial>

### maxUnreadCount

<partial id="chat-sdk/react-native/v3/_partials/common-content/core-components/channel-list/props/max_unread_count"></partial>

### numberOfSkeletons

<partial id="chat-sdk/react-native/v3/_partials/common-content/core-components/channel-list/props/number_of_skeletons"></partial>

### onAddedToChannel

<partial id="chat-sdk/react-native/v3/_partials/common-content/core-components/channel-list/props/on_added_to_channel"></partial>

### onChannelDeleted

<partial id="chat-sdk/react-native/v3/_partials/common-content/core-components/channel-list/props/on_channel_deleted"></partial>

### onChannelHidden

<partial id="chat-sdk/react-native/v3/_partials/common-content/core-components/channel-list/props/on_channel_hidden"></partial>

### onChannelVisible

<partial id="chat-sdk/react-native/v3/_partials/common-content/core-components/channel-list/props/on_channel_visible"></partial>

### onChannelTruncated

<partial id="chat-sdk/react-native/v3/_partials/common-content/core-components/channel-list/props/on_channel_truncated"></partial>

### onChannelUpdated

<partial id="chat-sdk/react-native/v3/_partials/common-content/core-components/channel-list/props/on_channel_updated"></partial>

### onMessageNew

<partial id="chat-sdk/react-native/v3/_partials/common-content/core-components/channel-list/props/on_message_new"></partial>

### onRemovedFromChannel

<partial id="chat-sdk/react-native/v3/_partials/common-content/core-components/channel-list/props/on_removed_from_channel"></partial>

### setFlatListRef

<partial id="chat-sdk/react-native/v3/_partials/common-content/core-components/channel-list/props/set_flat_list_ref"></partial>

### EmptyStateIndicator

<partial id="chat-sdk/react-native/v3/_partials/common-content/core-components/channel-list/props/empty_state_indicator"></partial>

### FooterLoadingIndicator

<partial id="chat-sdk/react-native/v3/_partials/common-content/core-components/channel-list/props/footer_loading_indicator"></partial>

### HeaderErrorIndicator

<partial id="chat-sdk/react-native/v3/_partials/common-content/core-components/channel-list/props/header_error_indicator"></partial>

### HeaderNetworkDownIndicator

<partial id="chat-sdk/react-native/v3/_partials/common-content/core-components/channel-list/props/header_network_down_indicator"></partial>

### List

<partial id="chat-sdk/react-native/v3/_partials/common-content/core-components/channel-list/props/list"></partial>

### ListHeaderComponent

<partial id="chat-sdk/react-native/v3/_partials/common-content/core-components/channel-list/props/list_header_component"></partial>

### LoadingErrorIndicator

<partial id="chat-sdk/react-native/v3/_partials/common-content/core-components/channel-list/props/loading_error_indicator"></partial>

### LoadingIndicator

<partial id="chat-sdk/react-native/v3/_partials/common-content/core-components/channel-list/props/loading_indicator"></partial>

### Preview

<partial id="chat-sdk/react-native/v3/_partials/common-content/core-components/channel-list/props/preview"></partial>

### PreviewAvatar

<partial id="chat-sdk/react-native/v3/_partials/common-content/core-components/channel-list/props/preview_avatar"></partial>

### PreviewMessage

<partial id="chat-sdk/react-native/v3/_partials/common-content/core-components/channel-list/props/preview_message"></partial>

### PreviewStatus

<partial id="chat-sdk/react-native/v3/_partials/common-content/core-components/channel-list/props/preview_status"></partial>

### PreviewTitle

<partial id="chat-sdk/react-native/v3/_partials/common-content/core-components/channel-list/props/preview_title"></partial>

### PreviewUnreadCount

<partial id="chat-sdk/react-native/v3/_partials/common-content/core-components/channel-list/props/preview_unread_count"></partial>

### Skeleton

<partial id="chat-sdk/react-native/v3/_partials/common-content/core-components/channel-list/props/skeleton"></partial>

---

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

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