MessageList

MessageList renders the loaded messages of the channel or the thread it sits in, in an inverted FlatList, and turns the user's scrolling into paginator calls. Inside a Thread it renders thread.messagePaginator, with the parent message above the replies; otherwise channel.messagePaginator. Message list UI explains what it shows, and how it differs from MessageFlashList.

Best practices

• Render it inside a Channel or a Thread. It reads the paginator, the composer's height and the message settings from the contexts they provide, so the same <MessageList /> works in both.
• Pass onThreadSelect in a channel. The replies button and the thread reply action call it with the message's Thread, and do nothing without it.
• Change how one message looks with the MessageItemView override, and the actions with messageActions on Channel. See Message actions. The list has no prop for either.
• Declare the components you pass, such as FooterComponent and HeaderComponent, outside the component that renders the list, and keep additionalFlatListProps stable.
• Use setFlatListRef to reach the FlatList, not a ref in additionalFlatListProps.

Basic usage

import type { Channel as StreamChannel, Thread } from "stream-chat";
import {
  Channel,
  MessageComposer,
  MessageList,
} from "stream-chat-react-native";

type ChannelScreenProps = {
  channel: StreamChannel;
  onOpenThread: (thread: Thread) => void;
};

export const ChannelScreen = ({
  channel,
  onOpenThread,
}: ChannelScreenProps) => (
  <Channel channel={channel}>
    <MessageList onThreadSelect={onOpenThread} />
    <MessageComposer />
  </Channel>
);

In a thread, render it inside <Thread thread={thread}> the same way, without onThreadSelect. How a component of yours reads the paginator the list renders is on Reading state in components.

Message grouping

The list groups consecutive messages from the same user. Each message gets a group style, top, middle, bottom or single, which decides its padding, its bubble corners, and whether the avatar and the footer with the time show: only the last message of a group, bottom or single, shows them, and a message that is still sending or failed keeps its footer.

• enableMessageGroupingByUser={false} on Channel, or noGroupByUser on the list, turns grouping off. Every message then gets an empty group style, so no message counts as the last of its group: no message shows the avatar, and only a message that is sending or failed shows the footer with the time.
• maxTimeBetweenGroupedMessages on Channel starts a new group when two messages are further apart than this many milliseconds.
• getMessageGroupStyle on Channel replaces the rule. It receives the message, its neighbors and the date separators around it, and returns the group styles. The default is the exported getGroupStyle.

What the list renders

Around the messages, the list renders:

For each message the list renders the date separator when a day starts, the Message override, and the unread separator under the last read message. A system message renders MessageSystem instead. Floating controls explains when each control shows, and Separators the separators.

Props

MessageListProps makes every prop optional. The props marked "from" a context default to that context's value, so you set them only to override it.

MessageListItemWithNeighbours, AttachmentPickerStore and MessageInputHeightStore aren't exported, so type a callback that receives them through MessageListProps, for example MessageListProps['setFlatListRef'].

Parts the list renders

These are the defaults of the override keys above. Replace one with WithComponents; Overriding components explains how. StickyHeader and UnreadMessagesNotification aren't exported, so a replacement can't wrap them.

InlineDateSeparator

Renders the date above the first message of a day. The text comes from the timestamp.InlineDateSeparator translation key, and screen readers get the full date.

InlineUnreadIndicator

Renders the unread separator under the last read message: "5 new messages", or "Unread Messages" without a count.

StickyHeader and DateHeader

StickyHeader receives the date of the topmost message on screen, formats it with the timestamp.StickyHeader translation key, and renders the DateHeader override with the result. It renders nothing without a date.

DateHeader renders the label.

UnreadMessagesNotification

Renders "5 unread", or "Unread Messages" without a count, with a close button. The count is the paginator's unread snapshot. The list passes markRead and an onCloseHandler that marks the channel read and hides the notification.

InlineLoadingMoreIndicator and InlineLoadingMoreRecentIndicator

The spinners the default FooterComponent and HeaderComponent render. They aren't override keys; pass your own FooterComponent or HeaderComponent instead.

NetworkDownIndicator takes no props. It shows "Waiting for network..." while the device is offline and "Reconnecting..." while the connection to Stream is down.

Related hooks

The paginator's API is on Message paginator, and jumping to a message on Message paginators.