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 UsageChannelList
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 ProvidersChannelList
contains the provider for the ChannelsContext
.
This can be accessed using the corresponding hook.
Context | Hook |
---|---|
ChannelsContext | useChannelsContext |
#
UI CustomizationsThe 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 Items
- Indicators
#
Propsrecommended 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.
#
ExampleFilter 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.
#
Exampleconst 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.
#
Exampleconst options = { message_limit: 100 };
note
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.
#
ExampleonSelect={(channel) => { /** navigation logic */ }}
note
A Channel
instance is not serializable and will therefore raise warnings if passed as a parameter through navigation to another screen.
Type |
---|
function |
Parameter | Description |
---|---|
channel | Channel instance |
#
additionalFlatListPropsAdditional props provided to the underlying FlatList.
#
Exampleconst flatListProps = { bounces: true };
<ChannelList additionalFlatListProps={flatListProps} />;
caution
Don't use additionalFlatListProps
to access the FlatList ref, use setFlatListRef
instead.
Type |
---|
object |
#
loadMoreThresholdSets the onEndReachedThreshold
of the underlying FlatList.
Type | Default |
---|---|
number | 2 |
#
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.
Type | Default |
---|---|
boolean | false |
#
maxUnreadCountMax number to display within unread notification badge. The value cannot be higher than 255, which is the limit on backend side.
Type | Default |
---|---|
number | 255 |
#
numberOfSkeletonsThe number of Skeleton
items to display in the LoadingIndicator
.
Type | Default |
---|---|
number | 6 |
#
onAddedToChannelOverride for Event Listener behavior when the user is added to a channel. The default behavior adds the channel to the list.
Type |
---|
function |
Parameter | Description |
---|---|
setChannels | Setter function for the internal channels state |
event | Event object corresponding to notification.added_to_channel |
#
onChannelDeletedOverride for Event Listener behavior when a channel is deleted. The default behavior removes the channel from the list.
Type |
---|
function |
Parameter | Description |
---|---|
setChannels | Setter function for the internal channels state |
event | Event object corresponding to channel.deleted |
#
onChannelHiddenOverride for Event Listener behavior when a channel is hidden. The default behavior removes the channel from the list.
Type |
---|
function |
Parameter | Description |
---|---|
setChannels | Setter function for the internal channels state |
event | Event object corresponding to channel.hidden |
#
onChannelVisibleOverride for Event Listener behavior when a channel is made visible. The default behavior adds the channel to the list.
Type |
---|
function |
Parameter | Description |
---|---|
setChannels | Setter function for the internal channels state |
event | Event object corresponding to channel.visible |
#
onChannelTruncatedOverride for Event Listener behavior when a channel is truncated. The default behavior reloads the list.
Type |
---|
function |
Parameter | Description |
---|---|
setChannels | Setter function for the internal channels state |
event | Event object corresponding to channel.truncated |
#
onChannelUpdatedOverride 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 |
Parameter | Description |
---|---|
setChannels | Setter function for the internal channels state |
event | Event object corresponding to channel.updated |
#
onMessageNewOverride 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 |
Parameter | Description |
---|---|
setChannels | Setter function for the internal channels state |
event | Event object corresponding to notification.message_new |
#
onRemovedFromChannelOverride for Event Listener behavior when the user is removed from a channel. The default behavior removes the channel from the list.
Type |
---|
function |
Parameter | Description |
---|---|
setChannels | Setter function for the internal channels state |
event | Event object corresponding to notification.removed_from_channel |
#
setFlatListRefCallback function to access the underlying FlatList ref.
#
Exampleconst flatListRef = useRef();
<ChannelList setFlatListRef={ref => (flatListRef.current = ref)} />;
Type |
---|
function |
Parameter | Description |
---|---|
ref | FlatList ref |
#
EmptyStateIndicatorRendered when the channel list is empty and not loading via the ListEmptyComponent prop on the FlatList.
Type | Default |
---|---|
component | EmptyStateIndicator |
#
FooterLoadingIndicatorRendered when loadingNextPage
from ChannelsContext
is true via the ListFooterComponent
prop on the FlatList.
Type | Default |
---|---|
component | ChannelListFooterLoadingIndicator |
#
HeaderErrorIndicatorRendered when error
from ChannelsContext
is true.
Type | Default |
---|---|
component | ChannelListHeaderErrorIndicator |
#
HeaderNetworkDownIndicatorRendered when isOnline
from ChatContext
is false.
Type | Default |
---|---|
component | ChannelListHeaderNetworkDownIndicator |
#
ListComponent to render the list of channels.
Type | Default |
---|---|
component | ChannelListMessenger |
#
ListHeaderComponentRendered when provided if the channel list is not empty via the ListHeaderComponent
prop on the FlatList.
Type |
---|
component |
#
LoadingErrorIndicatorRendered when error
from ChannelsContext
is true, and the channel list is empty and not loading.
Type | Default |
---|---|
component | LoadingErrorIndicator |
#
LoadingIndicatorRendered when the channel list is empty and loading via the ListEmptyComponent prop on the FlatList.
Type | Default |
---|---|
component | ChannelListLoadingIndicator |
#
PreviewList item rendered by the underlying FlatList.
Type | Default |
---|---|
component | ChannelPreviewMessenger |
#
PreviewAvatarAvatar component rendered within Preview
.
Type | Default |
---|---|
component | ChannelAvatar |
#
PreviewMessageMessage component rendered within Preview
.
Type | Default |
---|---|
component | ChannelPreviewMessage |
#
PreviewMutedStatusChannel muted status component rendered within Preview
.
Type | Default |
---|---|
component | ChannelPreviewMutedStatus |
#
PreviewStatusStatus component rendered within Preview
.
Type | Default |
---|---|
component | ChannelPreviewStatus |
#
PreviewTitleTitle component rendered within Preview
.
Type | Default |
---|---|
component | ChannelPreviewTitle |
#
PreviewUnreadCountUnread count component rendered within Preview
.
Type | Default |
---|---|
component | ChannelPreviewUnreadCount |
#
SkeletonRow item rendered in the LoadingIndicator
.
Type | Default |
---|---|
component | Skeleton |