Message list UI

The message list is the scrolling part of a channel or a thread. It shows the messages and loads more as the user scrolls. Use this page to choose between the SDK's two message lists, to learn what they show besides the messages, such as separators and notifications, and to customize them. How one message is put together is on Message UI. The props are in the MessageList and VirtualizedMessageList references.

This is the default message list of a channel, scrolled up after three new messages arrived. Its parts:

The typing indicator isn't in the image: it shows only while the list is scrolled to the bottom, and the notification and the button only while it isn't.

MessageList and VirtualizedMessageList

Both lists show the channel's messages, or a thread's replies when rendered inside a <Thread/>. They differ in what they put in the page:

Other differences, such as in the floating notifications and jumps, are in Differences between the lists.

Loading messages

The list shows the messages that channel.messagePaginator or thread.messagePaginator loaded. It shows one interval at a time, the active one: usually the latest messages, or those around a message the user jumped to.

• Scrolling to the top loads older messages, and scrolling to the bottom of an older interval loads newer ones.
• At the latest message, with the page visible, the list marks the channel or thread read. Read state, unread and receipts covers the exceptions.

Separators

Separators mark a point in the conversation. The list renders four kinds:

Before the first unread message, the list can also add a date separator, even within the same day. hideNewMessageSeparator removes it.

To replace a separator, register your own component under the key DateSeparator, UnreadMessagesSeparator or UnreadMessagesNotification in <WithComponents/>. The DateSeparator override also replaces the date above a thread's parent message.

The floating date separator shows while the user scrolls, and hides a second after the scrolling stops. It appears only once the date separator of the day at the top has scrolled out of view, so the same date is never shown twice. The lists find the date separators on screen by their str-chat__date-separator class and read each one's date from its data-date attribute, to decide when the floating one shows. A DateSeparator replacement keeps both, and adds the str-chat__date-separator--floating class when it gets floating, as the DateSeparator reference shows. While a date separator sits where the floating one is drawn, the floating one stays hidden, so it never covers it.

To change how a date separator writes its date, pass a formatDate function to <MessageList/> or <VirtualizedMessageList/>, which takes the Date and returns the text to show, such as "Mon, 12 May". It applies to the date separators between messages in <MessageList/>, and in both lists to the one above a thread's parent message. It doesn't apply to the floating one, or to those between messages in <VirtualizedMessageList/>. Localization covers date formats.

The unread messages separator keeps its place after opening the channel marks it read, so the user still sees where the new messages start. The paginator keeps that place in its unread snapshot. It goes away when the user catches up at the latest message, or clicks its ✕. Live view and unread on Message paginators explains the snapshot.

Message grouping

Messages a sender posts one after another form a group: their avatar and name show once, and the bubbles sit closer together. A group also ends:

• at a date separator, so each day starts a new group;
• at a system or error message;
• at a message with attachments, which always stands alone;
• before a message with reactions, which starts a new group;
• after an edited message.

Grouping is on by default in <MessageList/> and off in <VirtualizedMessageList/>. The groupByUser prop of either list turns it on or off.

Each message gets its place in its group: top, middle, bottom or single. The message UI styles the message from it.

Both lists take two props to change it:

• maxTimeBetweenGroupedMessages also starts a new group when two messages are further apart than this, in milliseconds. It isn't set by default.
• getGroupStyles replaces the function that decides each message's place in its group. It receives one object with the message and its neighbors.

Here is a getGroupStyles function that keeps the default grouping, but shows pinned messages on their own:

import { getGroupStyles, isLocalMessage, MessageList } from "stream-chat-react";

// Pinned messages stand alone; every other message is grouped as by default.
const pinnedStandAlone: typeof getGroupStyles = (params) =>
  isLocalMessage(params.message) && params.message.pinned
    ? "single"
    : getGroupStyles(params);

export const ChannelMessages = () => (
  <MessageList getGroupStyles={pinnedStandAlone} />
);

Floating notifications

Three elements float over the list to tell the user there is more to see:

• The floating unread messages separator also shows while the first unread message is below the visible area, with showUnreadNotificationAlways.
• The scroll-to-latest badge counts different things in a channel and in a thread. In a channel, it's the user's unread count, channel.state.read[userId].unread_messages, so it includes messages from before the user opened the channel, and drops to 0 once the channel is read. In a thread, it's the replies posted while the user was scrolled up.
• The new message notification counts the unread messages from the unread snapshot. Without them, it says "New Messages!".

Jumps on screen

A jump moves the list to one message, such as a quoted message, a search result, a pinned message, or the first unread one. Moving between channels, threads and messages lists every place in the UI that starts a jump.

On a jump, the list:

1. shows the messages around the target, loading them first if needed, with the target in the middle;
2. highlights the target with the str-chat__message--highlighted class. <MessageList/> removes it after 3 seconds in view (the jump's focusSignalTtlMs). <VirtualizedMessageList/> doesn't remove it: it stays until the next jump;
3. shows the scroll-to-latest button if the target isn't among the latest messages.

How the paginator jumps is on Message paginators.

Scrolling

Both lists follow new messages: they scroll down when the user sends a message, or when someone else does while the user is at the bottom. They don't follow while the user reads older messages after a jump.

Differences between the lists

The sections above describe each part. This table puts side by side how the parts differ between the two lists, in a channel and in a thread:

Two differences need a sentence more:

• The floating unread messages separator decides when to show in a different way. <MessageList/> watches where the separator in the list is. <VirtualizedMessageList/> renders only part of the list, so it compares the dates of the messages on screen with the user's last read.
• Marking read in <VirtualizedMessageList/> also waits until the last message is fully visible.

Changing what the list renders

Replacing parts

Register replacements with <WithComponents/>. Overriding components explains how overrides apply.

The keys for a message and its parts, MessageUI and VirtualMessage included, are on Message UI.

The default ThreadHead isn't exported, so a replacement for it can't render the default inside it.

Used in

• Reactions
• Pinned messages
• Read state, unread and receipts