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

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

When receiving channel information from channel events, the filters are not respected; the reason for this is that channel filters can get very complex, and implementing that filtering logic that supports all of the custom filter would be very hard to do. Implementing this on the backend side isn’t an option as it is inefficient and has to cater to different filters. So, to help you with it, you will have to override the notification.message_new event using the onNewMessageNotification and message.new event handlers using the onNewMessage prop of the ChannelList component.

Context Providers

ChannelList contains the provider for the ChannelsContext. This can be accessed using the corresponding hook.

ContextHook
ChannelsContextuseChannelsContext

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.

For optimal performance you should pass a filter object with a static reference. You can use a filter object that is not created inline; or memoize an inline filter object before passing it to the ChannelList to achieve this.

Type
Object

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.

For optimal performance you should pass a sort object with a static reference. You can use a sort object that is not created inline; or memoize an inline sort object before passing it to the ChannelList to achieve this.

Type
Object

options

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

Unlike the filters or sort objects, changing the options object alone will not re-query the list of channels.

Type
Object

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.

Channel instance is not serializable and will therefore raise warnings if passed as a parameter through navigation to another screen.

Type
(channel) ⇒ void

additionalFlatListProps

Additional props provided to the underlying FlatList.

Type
Object

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.

TypeDefault
Number0.1

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.

TypeDefault
Booleanfalse

maxUnreadCount

Max number to display within unread notification badge. The value cannot be higher than 255, which is the limit on backend side.

TypeDefault
Number255

numberOfSkeletons

The number of Skeleton items to display in the LoadingIndicator.

TypeDefault
Number6

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.

Type
Function
ParameterDescription
setChannelsSetter function for the internal channels state
eventEvent Object corresponding to notification.added_to_channel

onChannelDeleted

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

Type
Function
ParameterDescription
setChannelsSetter function for the internal channels state
eventEvent Object corresponding to channel.deleted

onChannelHidden

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

Type
Function
ParameterDescription
setChannelsSetter function for the internal channels state
eventEvent Object corresponding to channel.deleted

onChannelVisible

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

Type
Function
ParameterDescription
setChannelsSetter function for the internal channels state
eventEvent Object corresponding to channel.deleted

onChannelTruncated

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

Type
Function
ParameterDescription
setChannelsSetter function for the internal channels state
eventEvent Object corresponding to channel.deleted

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.

Type
Function
ParameterDescription
setChannelsSetter function for the internal channels state
eventEvent Object corresponding to channel.deleted

onMessageNew

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.

Warning: This function is deprecated. Use onNewMessageNotification instead.

Type
Function
ParameterDescription
setChannelsSetter function for the internal channels state
eventEvent Object corresponding to channel.deleted

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.

Type
Function
ParameterDescription
setChannelsSetter function for the internal channels state
eventEvent Object corresponding to channel.deleted

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.

Type
Function
ParameterDescription
lockChannelOrderLocks the order of the channels in the list so they will not dynamically reorder by most recent message when a new message is received.
setChannelsSetter function for the internal channels state.
eventEvent Object corresponding to message.new.

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.

Type
Function
ParameterDescription
setChannelsSetter function for the internal channels state.
eventEvent Object corresponding to channel.deleted.

setFlatlistRef

Callback function to access the underlying FlatList ref.

Type
(ref) ⇒ void

UI Component Props

EmptyStateIndicator

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

TypeDefault Value
ComponentTypeundefined | EmptyStateIndicator

FooterLoadingIndicator

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

TypeDefault Value
ComponentTypeundefined | ChannelListFooterLoadingIndicator

HeaderErrorIndicator

Rendered when error from ChannelsContext is true.

TypeDefault
ComponentTypeundefined | ChannelListHeaderErrorIndicator

HeaderNetworkDownIndicator

Rendered when isOnline from ChatContext is false.

TypeDefault
ComponentTypeundefined | ChannelListHeaderNetworkDownIndicator

List

Component to render the list of channels.

TypeDefault
ComponentTypeundefined | ChannelListMessenger

ListHeaderComponent

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

Type
ComponentType |undefined

LoadingErrorIndicator

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

TypeDefault
ComponentTypeundefined | LoadingErrorIndicator

LoadingIndicator

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

TypeDefault
ComponentTypeundefined | ChannelListLoadingIndicator

Preview

List item rendered by the underlying FlatList.

TypeDefault
ComponentTypeundefined | ChannelPreviewMessenger

PreviewAvatar

Avatar component rendered within Preview.

TypeDefault
ComponentTypeundefined | ChannelAvatar

PreviewMessage

Message component rendered within Preview.

TypeDefault
ComponentTypeundefined | ChannelPreviewMessage

PreviewMutedStatus

Channel muted status component rendered within Preview.

TypeDefault
ComponentTypeundefined | ChannelPreviewMutedStatus

PreviewStatus

Status component rendered within Preview.

TypeDefault
ComponentTypeundefined | ChannelPreviewStatus

PreviewTitle

Title component rendered within Preview.

TypeDefault
ComponentTypeundefined | ChannelPreviewTitle

PreviewUnreadCount

Unread count component rendered within Preview.

TypeDefault
ComponentTypeundefined | ChannelPreviewUnreadCount

Skeleton

Row item rendered in the LoadingIndicator.

TypeDefault
ComponentTypeundefined | Skeleton
© Getstream.io, Inc. All Rights Reserved.