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.

When a user presses on a channel in the list you can provide navigation logic via the 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.

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.

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.

const CustomPreviewTitle = ({ channel }) => (
  <Text>
    {channel.data.customProperty} - {channel.data.name}
  </Text>
);

<ChannelList PreviewTitle={CustomPreviewTitle} />;

List ItemsIndicators

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.

Example

Filter to query channels which users vishal or jaap are members of.

const filter = {
  type: "messaging",
  members: {
    $in: ["vishal", "jaap"],
  },
};

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.

Example

const sort = { last_updated: -1 };

options

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

Example

const options = { message_limit: 100 };

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.

Example

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

additionalFlatListProps

Additional props provided to the underlying FlatList.

Example

const flatListProps = { bounces: true };

<ChannelList additionalFlatListProps={flatListProps} />;

loadMoreThreshold

Sets the onEndReachedThreshold of the underlying FlatList.

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 Event Listener behavior when the user is added to a channel. The default behavior adds the channel to the list.

onChannelDeleted

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

onChannelHidden

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

onChannelVisible

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

onChannelTruncated

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

onChannelUpdated

Override for Event Listener behavior when a channel is updated. The default behavior updates the data on a channel with that from the event.

onMessageNew

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

onRemovedFromChannel

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

Example

const flatListRef = useRef();

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

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.

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.