ChannelList

ChannelList displays channels using React Native's FlatList.

ChannelList fetches channels via the client's query channels function. Pass filters, sort, and options via props.

Best Practices

• Memoize filters and sort to avoid unnecessary re-queries.
• Keep onSelect lightweight and handle navigation outside of render.
• Handle notification.message_new/message.new if you need strict filtering on real-time updates.
• Avoid passing Channel instances through navigation params; store them in state instead.
• Use sensible loadMoreThreshold values to reduce extra queries.

General Usage

ChannelList renders channels in a FlatList.

Note: Define the component within OverlayProvider and Chat so the required contexts are available.

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

Complete navigation example

Here's a practical example showing how to integrate ChannelList with React Navigation:

import React, { useMemo, useState, useEffect } from "react";
import { NavigationContainer } from "@react-navigation/native";
import { createStackNavigator } from "@react-navigation/stack";
import {
  Chat,
  OverlayProvider,
  ChannelList,
  Channel,
  MessageList,
  MessageInput,
  useCreateChatClient,
  useChatContext,
} from "stream-chat-react-native";

const Stack = createStackNavigator();

const ChannelListScreen = ({ navigation }) => {
  // Memoize filters and sort to prevent unnecessary re-renders
  const filters = useMemo(
    () => ({ members: { $in: ["user-id"] }, type: "messaging" }),
    [],
  );
  const sort = useMemo(() => [{ last_message_at: -1 }], []);

  return (
    <ChannelList
      filters={filters}
      sort={sort}
      onSelect={(channel) => {
        // Navigate to the channel screen
        // Note: Passing the channel CID, not the channel object
        navigation.navigate("Channel", { channelId: channel.cid });
      }}
    />
  );
};

const ChannelScreen = ({ route }) => {
  const { channelId } = route.params;
  const [channel, setChannel] = useState();
  const { client } = useChatContext();

  useEffect(() => {
    // Extract channel type and ID from CID (format: "type:id")
    const [type, id] = channelId.split(":");
    const channelInstance = client.channel(type, id);
    setChannel(channelInstance);
  }, [channelId, client]);

  if (!channel) return null;

  return (
    <Channel channel={channel}>
      <MessageList />
      <MessageInput />
    </Channel>
  );
};

export const App = () => {
  const chatClient = useCreateChatClient({
    apiKey: "YOUR_API_KEY",
    userData: { id: "user-id", name: "User Name" },
    tokenOrProvider: "YOUR_TOKEN",
  });

  if (!chatClient) return null;

  return (
    <OverlayProvider>
      <Chat client={chatClient}>
        <NavigationContainer>
          <Stack.Navigator>
            <Stack.Screen name="Channels" component={ChannelListScreen} />
            <Stack.Screen name="Channel" component={ChannelScreen} />
          </Stack.Navigator>
        </NavigationContainer>
      </Chat>
    </OverlayProvider>
  );
};

Context Providers

ChannelList provides ChannelsContext, accessible via its hook.

Props

filters

Filter object passed to query channels. You can filter on built-in and custom fields.

sort

Sort object passed to query channels. You can sort on built-in and custom fields.

options

Options object passed internally to the client query function as a parameter.

onSelect

Called when a user taps a channel. Receives the Channel instance for that item and is often used for navigation.

additionalFlatListProps

Additional props provided to the underlying FlatList.

loadMoreThreshold

Sets the onEndReachedThreshold. We recommend 0.1; higher values may trigger extra channelQuery calls.

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.

maxUnreadCount

Max unread badge value. Cannot exceed 255 (backend limit).

numberOfSkeletons

The number of Skeleton items to display in the LoadingIndicator.

onAddedToChannel

Override the default handler for when the user is added to a channel (default adds the channel).

onChannelDeleted

Override the default handler for channel deletion (default removes the channel).

onChannelHidden

Override the default handler for channel hidden (default removes the channel).

onChannelMemberUpdated

Override the default handler for member.updated. Required for pinning and archiving to work.

onChannelVisible

Override the default handler for channel visible (default adds the channel).

onChannelTruncated

Override the default handler for channel truncated (default reloads the list).

onChannelUpdated

Override the default handler for channel updated (default updates the channel data from the event).

onNewMessageNotification

Override the default handler for new message on an unwatched channel (default adds the channel).

onNewMessage

Override the default handler for new message on a watched channel (default moves the channel to the top).

onRemovedFromChannel

Override the default handler for when the user is removed from a channel (default removes the channel).

setFlatlistRef

Callback function to access the underlying FlatList ref.

queryChannelsOverride

A function that overrides the ChannelManager queryChannels method (StreamChat.queryChannels). Use it to query specific cids while still paginating (not possible via normal filters). Rules/assumptions:

• StreamChat.queryChannels must be called inside queryChannelsOverride (it updates important client state)
• The return type has to be Channel[] (which is the return type of StreamChat.queryChannels)
• limit and offset must still be respected so ChannelManager can paginate correctly

Example override:

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 this ChannelList configuration:

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

Pagination works as follows:

1. On the first page, 10 items will be loaded, which will be the first 10 cids
2. On the second page, queryChannelsOverride will be invoked with offset: 10 and limit: 10, so cids 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 cids (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 prop on the FlatList.

FooterLoadingIndicator

Rendered when loadingNextPage from ChannelsContext is true via the ListFooterComponent prop on the FlatList.

HeaderErrorIndicator

Rendered when error from ChannelsContext is true.

HeaderNetworkDownIndicator

Rendered when isOnline from ChatContext is false.

List

Component to render the list of channels.

ListHeaderComponent

Rendered when provided if the channel list is not empty via the ListHeaderComponent prop on the FlatList.

LoadingErrorIndicator

Rendered when error from ChannelsContext is true, and the channel list is empty and not loading.

LoadingIndicator

Rendered when the channel list is empty and loading via the ListEmptyComponent prop on the FlatList.

Preview

List item rendered by the underlying FlatList.

PreviewAvatar

Avatar component rendered within Preview.

PreviewMessage

Message component rendered within Preview.

PreviewMutedStatus

Channel muted status component rendered within Preview.

PreviewStatus

Status component rendered within Preview.

PreviewTitle

Title component rendered within Preview.

PreviewUnreadCount

Unread count component rendered within Preview.

Skeleton

Row item rendered in the LoadingIndicator.

Channel List Event Listener Options

filters

Filter object passed internally to the client query function as a parameter. You can filter a query on built-in and custom fields on a Channel.

sort

Sort object passed internally to the client query function as a parameter. You can sort a query on built-in and custom fields on a Channel.