Skip to main content

VirtualizedMessageList

The VirtualizedMessageList component renders a scrollable list of messages. It differs from the standard MessageList in that it handles UI virtualization by default. Virtualization is a technique used to emulate large lists of elements by rendering as few items as possible to maintain performance and decrease the load on the DOM, while preserving the user experience. These qualities make the VirtualizedMessageList ideal for livestream use cases, where a single channel may have thousands of currently active users.

Similar to the MessageList, the UI for each individual message is rendered conditionally based on its message.type value. The list renders date separators, new message notifications, system messages, deleted messages, and standard messages containing text and/or attachments.

By default, the VirtualizedMessageList loads the most recent 25 messages held in the channel.state. More messages are fetched from the Stream Chat API and loaded into the DOM on scrolling up the list. The currently loaded messages are held in the ChannelStateContext and can be referenced with our custom hook.

const { messages } = useChannelStateContext();

The VirtualizedMessageList has no required props and by default pulls overridable data from the various contexts established in the Channel component. Customization of the messages rendered within the list is handled by the Message UI component.

Basic Usage#

As a context consumer, the VirtualizedMessageList component must be rendered as a child of the Channel component. It can be rendered with or without a provided messages prop. Providing your own messages value will override the default value drawn from the ChannelStateContext.

Example 1 - without messages prop

<Chat client={client}>
<ChannelList />
<Channel>
<VirtualizedMessageList />
<MessageInput />
</Channel>
</Chat>

Example 2 - with messages prop

const customMessages = [
// array of messages
];

<Chat client={client}>
<ChannelList />
<Channel>
<VirtualizedMessageList messages={customMessages} />
<MessageInput />
</Channel>
</Chat>;

Scroll Behavior Optimization#

By default, the virtualized message list uses the latest message (which gets rendered first) in the list as the default item size. This can lead to inaccurate scroll thumb size or scroll jumps if the last item is unusually tall (for example, an attachment). To improve this behavior, set the defaultItemHeight property to a value close (or equal to) the height of the usual messages.

<VirtualizedMessageList messages={customMessages} defaultItemHeight={76} />

Props#

additionalVirtuosoProps#

Additional props to be passed the underlying react-virtuoso virtualized list dependency.

Type
object

closeReactionSelectorOnClick#

If true, picking a reaction from the ReactionSelector component will close the selector.

TypeDefault
booleanfalse

customMessageRenderer#

Custom message render function, overrides the default messageRenderer function defined in the component.

Type
( messages: StreamMessage[], index: number ) => React.ReactElement

defaultItemHeight#

If set, the default item height is used for the calculation of the total list height. Use if you expect messages with a lot of height variance.

Type
number

disableDateSeparator#

If true, disables the injection of date separator UI components.

TypeDefault
booleantrue

hasMore#

Whether or not the list has more items to load.

TypeDefault
booleanChannelStateContextValue['hasMore']

hideDeletedMessages#

If true, removes the MessageDeleted components from the list.

TypeDefault
booleanfalse

hideNewMessageSeparator#

If true, hides the DateSeparator component that renders when new messages are received in a channel that's watched but not active.

TypeDefault
booleanfalse

loadingMore#

Whether or not the list is currently loading more items.

TypeDefault
booleanChannelStateContextValue['loadingMore']

loadMore#

Function called when more messages are to be loaded, provide your own function to override the handler stored in context.

TypeDefault
functionChannelActionContextValue['loadMore']

Message#

Custom UI component to display an individual message.

TypeDefault
componentFixedHeightMessage

messageLimit#

The limit to use when paginating messages.

TypeDefault
number100

messages#

The messages to render in the list, provide your own array to override the data stored in context.

TypeDefault
arrayChannelStateContextValue['messages']

overscan#

The amount of extra content the list should render in addition to what's necessary to fill in the viewport.

TypeDefault
number0

scrollSeekPlaceHolder#

Custom data passed to the list that determines when message placeholders should be shown during fast scrolling.

Type
object

scrollToLatestMessageOnFocus#

If true, the list will scroll to the latest message when the window regains focus.

TypeDefault
booleanfalse

shouldGroupByUser#

If true, group messages belonging to the same user, otherwise show each message individually.

TypeDefault
booleanfalse

separateGiphyPreview#

If true, the Giphy preview will render as a separate component above the MessageInput, rather than inline with the other messages in the list.

TypeDefault
booleanfalse

stickToBottomScrollBehavior#

The scroll-to behavior when new messages appear. Use 'smooth' for regular chat channels and 'auto' (which results in instant scroll to bottom) if you expect high throughput.

TypeDefault
'smooth' | 'auto''smooth'

threadList#

If true, indicates that the current VirtualizedMessageList component is part of a Thread.

TypeDefault
booleanfalse

Did you find this page helpful?