ChannelList

The ChannelList displays a list of channels using React Native’s FlatList component.

ChannelList internally fetches a list of channels using the client’s query channels function; to which you can pass the filters, sort and options parameters via props on ChannelList.

General Usage

The ChannelList can be used to display the all the participants in the form of FlatList.

Note: The component should be defined within the OverlayProvider and Chat wrappers so that all the contexts are provided to the component internally.

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.

Props

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.

options

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

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.

additionalFlatListProps

Additional props provided to the underlying FlatList.

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.

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 number to display within unread notification badge. The value cannot be higher than 255, which is the limit on backend side.

numberOfSkeletons

The number of Skeleton items to display in the LoadingIndicator.

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.

onChannelDeleted

Override for the default Event Listener behavior when a channel is deleted. The default behavior removes the channel from the list.

onChannelHidden

Override for the default Event Listener behavior when a channel is hidden. The default behavior removes the channel from the list.

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.

onChannelVisible

Override for the default Event Listener behavior when a channel is made visible. The default behavior adds the channel to the list.

onChannelTruncated

Override for the default Event Listener behavior when a channel is truncated. The default behavior reloads the list.

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.

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.

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.

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.

setFlatlistRef

Callback function to access the underlying FlatList ref.

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

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

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:

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