Skip to main content


The MessageList component renders a scroll-able list of messages.

The MessageList displays messages using pagination, new messages are loaded when the user scrolls to the top of the list.


Custom message component

If you want to customize how messages are displayed in the list, head over to the Message component's page.

Date separator

Custom message list

The message list contains a lot of low-level logic related to scrolling, we don't advise to create your own message list component, however it's possible: see our customization guide on how to provide your own message list component.


If you want to create your own message list, you can use the ChannelService to receive the necessary messages and interact with the Stream API.

Other building blocks, that you might find useful:

Message group styles

Message group styles makes the message list more readable, by grouping messages from the same author on the same day together. The grouping assigns a CSS class to every message, if you want to take advantage of this functionality, you can use the getGroupStyles utility function.

Example 1 - Messages with group styles

Example 2 - Messages without group styles

Example 2 - Using a custom message component

If you only want to customize the messages (not the whole list), see the message customization guide.

Inputs and outputs


mode: "thread" | "main" = 'main'

Determines if the message list should display channel messages or thread messages.

Defined in



direction: "bottom-to-top" | "top-to-bottom" = 'bottom-to-top'

The direction of the messages in the list, bottom-to-top means newest message is at the bottom of the message list and users scroll upwards to load older messages

Defined in



messageOptionsTrigger: "message-row" | "message-bubble" = 'message-row'

Determines what triggers the appearance of the message options: by default you can hover (click on mobile) anywhere in the row of the message (message-row option), or you can set message-bubble, in that case only a hover (click on mobile) in the message bubble will trigger the options to appear.

Defined in



hideJumpToLatestButtonDuringScroll: boolean = false

You can hide the "jump to latest" button while scrolling. A potential use-case for this input would be to workaround a known issue on iOS Safar

deprecated This scroll issue has been resolved, no need to use this workaround anymore.

Defined in



customMessageActions: CustomMessageActionItem<any>[] = []

A list of custom message actions to be displayed in the message action box

Defined in



displayDateSeparator: boolean = true

If true date separators will be displayed

Defined in



dateSeparatorTextPos: "center" | "right" | "left" = 'center'

If date separators are displayed, you can set the horizontal position of the date text. If openMessageListAt is last-read-message it will also set the text position of the new messages indicator.

Defined in



openMessageListAt: "last-message" | "last-read-message" = 'last-message'

last-message option will open the message list at the last message, last-read-message will open the list at the last unread message. This option only works if mode is main.

Defined in



displayLoadingIndicator: boolean = true

You can turn on and off the loading indicator that signals to users that more messages are being loaded to the message list

Defined in


Did you find this page helpful?