# ChannelsContext

`ChannelsContext` is provided by [`ChannelList`](https://getstream.io/chat/docs/sdk/react-native/core-components/channel-list/). If you are not familiar with the React Context API, see the [React docs](https://reactjs.org/docs/context.html).

## Best Practices

- Use `useChannelsContext` for consistent access and typings.
- Treat `channels` as read-only; use context helpers to mutate list state.
- Use `reloadList` when filters change, and `refreshList` for pull-to-refresh.
- Check `hasNextPage` and `loadingNextPage` before triggering pagination.
- Keep list UI components lightweight to preserve scroll performance.

## Basic Usage

Consume `ChannelsContext` in any child of `ChannelList`:

```tsx
import { useContext } from "react";
import { ChannelsContext } from "stream-chat-react-native";

const { channels, reloadList } = useContext(ChannelsContext);
```

Alternatively, use the `useChannelsContext` hook.

```tsx
import { useChannelsContext } from "stream-chat-react-native";

const { channels, reloadList } = useChannelsContext();
```

## Values

| Value                     | Description                                                                                                                                                                                                                                                                                                                                                                              | Type                            |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| `additionalFlatListProps` | Additional props provided to the underlying [FlatList](https://reactnative.dev/docs/flatlist#props). Don't use `additionalFlatListProps` to access the FlatList ref, use `setFlatListRef` instead.                                                                                                                                                                                       | `object`                        |
| `channels`                | Array of channels currently loaded within the `ChannelList` component.                                                                                                                                                                                                                                                                                                                   | `array`                         |
| `channelListInitialized`  | A control prop used to determine whether the first query of the channel list has succeeded. Don't set this prop manually, it is set automatically by the `ChannelList` component.                                                                                                                                                                                                        | `boolean`                       |
| `error`                   | True if a call to query channels API call within `ChannelList` component results in error, either during first load or during pagination.                                                                                                                                                                                                                                                | `Error object \| boolean`       |
| `hasNextPage`             | False if `ChannelList` has loaded all channels for the current filters.                                                                                                                                                                                                                                                                                                                  | `boolean`                       |
| `loadingChannels`         | True if `ChannelList` component is loading the first page of channels.                                                                                                                                                                                                                                                                                                                   | `boolean`                       |
| `loadMoreThreshold`       | Sets the `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. Defaults to `0.1`.                                                                                                                                                    | `number`                        |
| `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` is true.                                                                                                                                                                                                              | `boolean`                       |
| `loadNextPage`            | Loads the next page for `ChannelList`.                                                                                                                                                                                                                                                                                                                                                   | `function`                      |
| `maxUnreadCount`          | Max number to display within unread notification badge. The value cannot be higher than 255, which is the limit on backend side. Defaults to `255`.                                                                                                                                                                                                                                      | `number`                        |
| `mutedStatusPosition`     | Position of the muted status component within the Preview. Defaults to `'inlineTitle'`.                                                                                                                                                                                                                                                                                                  | `trailingBottom \| inlineTitle` |
| `pinnedStatusPosition`    | Position of the pinned status component within the Preview. Defaults to `'inlineTitle'`.                                                                                                                                                                                                                                                                                                 | `trailingBottom \| inlineTitle` |
| `swipeActionsEnabled`     | If true, the user can swipe to perform actions on a channel. Defaults to `true`.                                                                                                                                                                                                                                                                                                         | `boolean`                       |
| `numberOfSkeletons`       | The number of Skeleton items to display in the LoadingIndicator. Defaults to `8`.                                                                                                                                                                                                                                                                                                        | `number`                        |
| `onSelect`                | Function called when a user presses an item in the `ChannelList`. The function is called with the Channel instance corresponding to the list item as the only parameter. This callback is often used for navigating to a channel screen. Note: a `Channel` instance is not serializable and will therefore raise warnings if passed as a parameter through navigation to another screen. | `function`                      |
| `refreshing`              | True if `ChannelList` component is refreshing the list (using `refreshList` function call). Refreshing state will be triggered either when user executes pull-to-refresh gesture or if network connection is being recovered.                                                                                                                                                            | `boolean`                       |
| `refreshList`             | Function to manually re-sync or refresh the channels in `ChannelList` component. Calling `refreshList` will trigger a RefreshControl on underlying FlatList component.                                                                                                                                                                                                                   | `function`                      |
| `reloadList`              | Manually reloads channels in `ChannelList`. Calling `reloadList` clears the current list and shows a loading indicator until new results arrive.                                                                                                                                                                                                                                         | `function`                      |
| `setFlatListRef`          | Callback function to access the underlying FlatList ref.                                                                                                                                                                                                                                                                                                                                 | `function`                      |

## Examples

### additionalFlatListProps

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

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

### onSelect

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

### setFlatListRef

```tsx
const flatListRef = useRef();

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

---

For the most recent version of this documentation, visit [https://getstream.io/chat/docs/sdk/react-native/contexts/channels-context/](https://getstream.io/chat/docs/sdk/react-native/contexts/channels-context/).