Skip to main content
Version: v4

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_message_at: -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.

ContextHook
ChannelsContextuseChannelsContext

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

Props#

recommended
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'],
},
};
note

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

recommended
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_message_at: -1 };
note

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

recommended
options#

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

Example#

const options = { message_limit: 100 };
note

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

Type
object

recommended
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 */ }}
note

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

Type
function
ParameterDescription
channelChannel instance

additionalFlatListProps#

Additional props provided to the underlying FlatList.

Example#

const flatListProps = { bounces: true };

<ChannelList additionalFlatListProps={flatListProps} />;
caution

Don't use additionalFlatListProps to access the FlatList ref, use setFlatListRef instead.

Type
object

loadMoreThreshold#

Sets the onEndReachedThreshold of the underlying FlatList.

TypeDefault
number2

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

onChannelVisible#

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

onChannelTruncated#

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

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.

Type
function
ParameterDescription
setChannelsSetter function for the internal channels state
eventEvent object corresponding to channel.updated

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.

Type
function
ParameterDescription
setChannelsSetter function for the internal channels state
eventEvent object corresponding to notification.message_new

onRemovedFromChannel#

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

setFlatListRef#

Callback function to access the underlying FlatList ref.

Example#

const flatListRef = useRef();

<ChannelList setFlatListRef={ref => (flatListRef.current = ref)} />;
Type
function
ParameterDescription
refFlatList ref

EmptyStateIndicator#

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

TypeDefault
componentEmptyStateIndicator

FooterLoadingIndicator#

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

TypeDefault
componentChannelListFooterLoadingIndicator

HeaderErrorIndicator#

Rendered when error from ChannelsContext is true.

TypeDefault
componentChannelListHeaderErrorIndicator

HeaderNetworkDownIndicator#

Rendered when isOnline from ChatContext is false.

TypeDefault
componentChannelListHeaderNetworkDownIndicator

List#

Component to render the list of channels.

TypeDefault
componentChannelListMessenger

ListHeaderComponent#

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

Type
component

LoadingErrorIndicator#

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

TypeDefault
componentLoadingErrorIndicator

LoadingIndicator#

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

TypeDefault
componentChannelListLoadingIndicator

Preview#

List item rendered by the underlying FlatList.

TypeDefault
componentChannelPreviewMessenger

PreviewAvatar#

Avatar component rendered within Preview.

TypeDefault
componentChannelAvatar

PreviewMessage#

Message component rendered within Preview.

TypeDefault
componentChannelPreviewMessage

PreviewMutedStatus#

Channel muted status component rendered within Preview.

TypeDefault
componentChannelPreviewMutedStatus

PreviewStatus#

Status component rendered within Preview.

TypeDefault
componentChannelPreviewStatus

PreviewTitle#

Title component rendered within Preview.

TypeDefault
componentChannelPreviewTitle

PreviewUnreadCount#

Unread count component rendered within Preview.

TypeDefault
componentChannelPreviewUnreadCount

Skeleton#

Row item rendered in the LoadingIndicator.

TypeDefault
componentSkeleton

Did you find this page helpful?