Message List View

LAST EDIT Jul 21 2021
This documentation is for the old stream-chat-android UI implementation. Check out MessageListView in our new UI components for an updated version.

The message list renders a list of messages. It implements all the features you expect from a chat/message list view:

  • Reactions

  • Editing

  • Typing indicators

  • Read state

  • Rich URL previews

  • Threads

The example below shows how to use the MessageListView in your layout:

To render the list of messages you need to connect the view to the MessageListViewModel using MessageListViewModelBinding:

The view model provides the view with:

  • The list of messages

  • The ability to mark messages as read

  • Pagination/ loading more content

  • Keeping track if there are new messages (that are not shown since you're scrolled up)

  • The current channel

  • Edit message state

  • Start thread state

  • Button to scroll to the bottom.

  • Count of new messages.

Listeners

Copied!

The following listeners can be set:

  • setMessageClickListener

  • setMessageLongClickListener

  • setMessageRetryListener

  • setAttachmentClickListener

  • setReactionViewClickListener

  • setUserClickListener

  • setReadStateClickListener

  • setOnStartThreadListener

Handlers

Copied!

The following handlers can be set:

  • setEndRegionReachedHandler

  • setLastMessageReadHandler

  • setOnMessageEditHandler

  • setOnMessageDeleteHandler

  • setOnStartThreadHandler

  • setOnMessageFlagHandler

  • setOnSendGiphyHandler

  • setOnMessageRetryHandler

Customizations

Copied!

The message list view exposes multiple methods which might be helpful if you decide not to use default view model but create your own controller instead:

  • init()

  • setScrollButtonBehaviour()

  • setNewMessagesBehaviour()

  • setScrollButtonBackgroundResource()

  • setScrollButtonBackground()

  • setScrollButtonIconResource()

  • setScrollButtonIcon()

  • setAttachmentViewHolderFactory()

  • setMessageViewHolderFactory()

  • setBubbleHelper()

  • displayNewMessage()

  • scrollToBottom()

  • setLoadingView()

  • setEmptyStateView()

Customizing the message list using attributes

Copied!

You can use the following properties in your XML to change your MessageListView:

Behaviour

Copied!
nametypedescriptiondefaultoptional
app:streamNewMessagesBehaviourenum. Options: 1- scroll_to_bottom, 2 - count_new_messagesBehaviour for new messages when user is scrolling in the chat. count_new_messages

Scroll to bottom button

Copied!
nametypedescriptiondefaultoptional
app:streamNewMessagesTextSinglestringText for one new message. Example: "1 New message"-
app:streamNewMessagesTextPlural stringText for many new messages. Example: "5 New messages"-
app:streamScrollButtonBackgroundreferenceBackground of the scroll to bottom button - This can be useful to change the color and shape of the button. round shape with accent color
app:streamButtonIconreferenceIcon in the buttonBottom arrow
app:streamDefaultScrollButtonEnabledbooleanEnable or disable the Scroll ButtonTrue

Avatar

Copied!
nametypedescriptiondefaultoptional
app:streamAvatarWidthdimension32dp
app:streamAvatarHeightdimension32dp
app:streamAvatarBorderWidthdimension3dp
app:streamAvatarBorderColorcolorWHITE
app:streamAvatarBackGroundColorcolorstream_gray_dark
app:streamAvatarTextSizedimension14sp
app:streamAvatarTextColorcolorWHITE
app:streamAvatarTextStylenormal, bold, italicbold
app:streamAvatarTextFontreference-
app:streamAvatarTextFontAssetsstring-

Read State

Copied!
nametypedescriptiondefaultoptional
app:streamShowReadStatebooleantrue
app:streamReadStateAvatarWidthdimension14dp
app:streamReadStateAvatarHeightdimension14dp
app:streamReadStateTextSizedimension8sp
app:streamReadStateTextColorcolorBLACK
app:streamReadStateTextStylenormal, bold, italicbold
app:streamReadStateTextFontreference-
app:streamReadStateTextFontAssetsstring-
app:streamShowDeliveredStatebooleantrue
app:streamShowReadStatebooleantrue

Reactions

Copied!
nametypedescriptiondefaultoptional
app:streamReactionEnabledbooleantrue
app:streamrReactionViewBgDrawablereference-
app:streamReactionViewBgColorcolor#292929
app:streamReactionViewEmojiSizedimension12sp
app:streamReactionViewEmojiMargindimension1dp
app:streamReactionInputbgColorcolor#292929
app:streamReactionInputEmojiSizedimension27sp
app:streamReactionInputEmojiMargindimension5dp

Message

Copied!
nametypedescriptiondefaultoptional
app:streamMessageTextSizeMinedimension15sp
app:streamMessageTextSizeTheirsdimension15sp
app:streamMessageTextColorMinecolorBLACK
app:streamMessageTextColorTheirscolorBLACK
app:streamMessageTextStyleMinenormal, bold, italicnormal
app:streamMessageTextStyleTheirsnormal, bold, italicnormal
app:streamMessageTextFontMinereference-
app:streamMessageTextFontTheirsreference-
app:streamMessageTextFontMineAssetsstring-
app:streamMessageTextFontTheirsAssetsstring-
app:streamMessageBubbleDrawableMinereference-
app:streamMessageBubbleDrawableTheirsreference-
app:streamMessageTopLeftCornerRadiusMinedimension16dp
app:streamMessageTopRightCornerRadiusMinedimension16dp
app:streamMessageBottomRightCornerRadiusMinedimension2dp
app:streamMessageBottomLeftCornerRadiusMinedimension16dp
app:streamMessageTopLeftCornerRadiusTheirsdimension16dp
app:streamMessageTopRightCornerRadiusTheirsdimension16dp
app:streamMessageBottomRightCornerRadiusTheirsdimension16dp
app:streamMessageBottomLeftCornerRadiusTheirsdimension2dp
app:streamMessageBackgroundColorMinecolor#0D000000
app:streamMessageBackgroundColorTheirscolorWHITE
app:streamMessageBorderColorMinecolor#14000000
app:streamMessageBorderColorTheirscolor#14000000
app:streamMessageBorderWidthMinedimension1dp
app:streamMessageBorderWidthTheirsdimension1dp
app:streamMessageLinkTextColorMinecolor-
app:streamMessageLinkTextColorTheirscolor-

Attachment

Copied!
nametypedescriptiondefaultoptional
app:streamAttachmentBackgroundColorMinecolorstreamMessageBackgroundColorMine
app:streamAttachmentBackgroundColorTheirscolorstreamMessageBackgroundColorTheirs
app:streamAttachmentBorderColorMinecolorstreamMessageBorderColorMine
app:streamAttachmentBorderColorTheirscolorstreamMessageBorderColorTheirs
app:streamAttachmentTitleTextSizeMinedimension13sp
app:streamAttachmentTitleTextSizeTheirsdimension13sp
app:streamAttachmentTitleTextColorMinecolor#026DFE
app:streamAttachmentTitleTextColorTheirscolor#026DFE
app:streamAttachmentTitleTextStyleMinenormal, bold, italicbold
app:streamAttachmentTitleTextStyleTheirsnormal, bold, italicbold
app:streamAttachmentTitleTextFontMinereference-
app:streamAttachmentTitleTextFontTheirsreference-
app:streamAttachmentTitleTextFontAssetsMinestring-
app:streamAttachmentTitleTextFontAssetsTheirsstring-
app:streamAttachmentDescriptionTextSizeMinedimension11sp
app:streamAttachmentDescriptionTextSizeTheirsdimension11sp
app:streamAttachmentDescriptionTextColorMinecolorstream_gray_dark
app:streamAttachmentDescriptionTextColorTheirscolorstream_gray_dark
app:streamAttachmentDescriptionTextStyleMinenormal, bold, italicnormal
app:streamAttachmentDescriptionTextStyleTheirsnormal, bold, italicnormal
app:streamAttachmentDescriptionTextFontMinereference-
app:streamAttachmentDescriptionTextFontTheirsreference-
app:streamAttachmentDescriptionTextFontAssetsMinestring-
app:streamAttachmentDescriptionTextFontAssetsTheirsstring-
app:streamAttachmentFileSizeTextSizeMinedimension12sp
app:streamAttachmentFileSizeTextSizeTheirsdimension12sp
app:streamAttachmentFileSizeTextColorMinecolorstream_gray_dark
app:streamAttachmentFileSizeTextColorTheirscolorstream_gray_dark
app:streamAttachmentFileSizeTextStyleMinenormal, bold, italicbold
app:streamAttachmentFileSizeTextStyleTheirsnormal, bold, italicbold
app:streamAttachmentFileSizeTextFontMinereference-
app:streamAttachmentFileSizeTextFontTheirsreference-
app:streamAttachmentFileSizeTextFontAssetsMinestring-
app:streamAttachmentFileSizeTextFontAssetsTheirsstring-

Date Separator

Copied!
nametypedescriptiondefaultoptional
app:streamDateSeparatorDateTextSizedimension12sp
app:streamDateSeparatorDateTextColorcolorstream_gray_dark
app:streamDateSeparatorDateTextStylenormal, bold, italicbold
app:streamDateSeparatorDateTextFontreference-
app:streamDateSeparatorDateTextFontAssetsstring-
app:streamDateSeparatorLineWidthdimension1dp
app:streamDateSeparatorLineColorcolorstream_gray_dark
app:streamDateSeparatorLineDrawablereference-

Message details

Copied!
nametypedescriptiondefaultoptional
app:streamMessageUserNameTextSizedimension11sp
app:streamMessageUserNameTextColorcolorstream_gray_dark
app:streamMessageUserNameTextStylenormal, bold, italicnormal
app:streamMessageUserNameTextFontreference-
app:streamMessageUserNameTextFontAssetsstring-
app:streamMessageDateTextSizeMinedimension11sp
app:streamMessageDateTextSizeTheirsdimension11sp
app:streamMessageDateTextColorMinecolorstream_gray_dark
app:streamMessageDateTextColorTheirscolorstream_gray_dark
app:streamMessageDateTextStyleMinenormal, bold, italicnormal
app:streamMessageDateTextStyleTheirsnormal, bold, italicnormal
app:streamMessageDateTextFontMinereference-
app:streamMessageDateTextFontAssetsMinestring-
app:streamUserNameShowbooleantrue
app:streamMessageDateShowbooleantrue

Copied!

Customizing the message list - BubbleHelper

Copied!

Message Bubbles can be quite complex in messaging apps. Many messaging apps will change the bubble layout based on:

  • The message position in a group of messages (top, middle, bottom)

  • The overall position of the message on the screen

  • If the message is yours or written by someone else

  • If the message has attachments

To allow you to customize the message bubble rendering we allow you to set your own message Bubble Helper. Here's an example of how to set a custom bubble helper.

For some messaging use cases, you'll run into the issue that you need to create many different drawables. One library that can help with that is DrawableToolbox which simplifies the programmatic creation of drawables.

Custom Attachment Type

Copied!

You can customize the layout for a specific type of message or attachment. Example use cases include adding a form, a live location, a checkout flow, etc.

These are the steps for creating your own attachment type:

  1. Implement an Attachment ViewHolder, with your custom layout

  2. Create an AttachmentViewHolderFactory that creates instances of your ViewHolder

  3. Tell the MessageListView to use your custom AttachmentViewHolderFactory

The Kotlin Chat Tutorial explains this in more detail.

Creating custom scroll-to-bottom button

Copied!

Although it is possible to customize the default button, sometimes a user may want a completely different view.

As MessageListView extends from ConstraintLayout, any view can be inserted inside of it and used as the button to scroll to button and show the count of new messages.

Then the behaviour of the button can be set with the method setScrollButtonBehaviour implementing the interface MessageListView.ScrollButtonBehaviour, as an example: