ChatMessageList API

API reference docs for the React ChatMessageList component. Learn about the props, CSS, and other APIs of this exported module.

Demos

For examples and details on the usage of this React component, visit the component demo pages:

Import

import { ChatMessageList } from '@mui/x-chat/ChatMessageList';
// or
import { ChatMessageList } from '@mui/x-chat';

Learn about the difference by reading this guide on minimizing bundle size.

Props

Props of the native component are also available.

Name	Type	Default	Description
autoScroll	{ buffer?: number } \| bool	true	Controls automatic scrolling to the bottom when new messages arrive or streaming content grows, as long as the user is within `buffer` pixels of the bottom. `true` – enable with the default buffer (150 px). `{ buffer: number }` – enable with a custom threshold. `false` – disable (the scroll-to-bottom affordance is still available). Scrolling when the user sends a message is always active.
enableRovingFocus	bool	true	Whether the message list manages a roving tabindex over its messages: the list is a single Tab stop, ArrowUp/ArrowDown (plus Home/End) move focus between messages, Enter drills into a message's interior controls and Escape returns to the message. Disable when rendering fully custom rows that manage focus themselves.
features	{ dateDivider?: bool, streamingIndicator?: 'auto' \| bool, unreadMarker?: bool }	-	Feature flags for the row extras rendered by the default row: the opt-in dividers (`dateDivider` / `unreadMarker`, disabled by default) and the streaming indicator (`streamingIndicator`, `'auto'` by default). Ignored when a custom `renderItem` replaces the default row.
onReachBottom	func	-	Callback fired when the viewport enters the bottom zone of the list — within `autoScroll.buffer` pixels (150 by default; `estimatedItemSize` when `autoScroll` is disabled) of the bottom edge. Fires once per entry: it does not fire again until the user scrolls away from the bottom and back. Entries caused by programmatic scrolls (`scrollToBottom()`, the scroll-to-bottom affordance, the forced scroll after the user sends a message) count. It does not fire on mount, while the list stays pinned to the bottom during streaming, when new messages arrive while already at the bottom, or when the conversation (item set) is switched. Growing the buffer so that it newly encloses the current position counts as entering the zone.
onReachTop	func	-	Callback fired when the viewport enters the top zone of the list — within `estimatedItemSize` pixels (84 by default) of the top edge. Fires once per entry: it does not fire again until the user scrolls away from the top, past the threshold, and back. It is coupled to history loading: it only fires when more history is available and no history page load is in flight, right before the next page is requested.
overlay	node	null	Floating layer rendered above the message list, anchored to its bottom edge; pointer-transparent.
renderItem	func	-	Render a custom row for each message. When omitted, the default row used by `ChatBox` is rendered (group → message → avatar → content, with conditional inline meta, external meta in compact variant, and message actions slot). Provide a function to fully replace the row; use slot overrides to tweak individual sub-components without losing the default chrome.

The component cannot hold a ref.

CSS classes

These class names are useful for styling with CSS. They are applied to the component's slots when specific states are triggered.

Class name	Rule name	Description
.MuiChatMessageList-content	content	Styles applied to the message list content element.
.MuiChatMessageList-root	root	Styles applied to the message list root element.
.MuiChatMessageList-scroller	scroller	Styles applied to the message list scroller element.

You can override the style of the component using one of these customization options:

With a global class name.
With a rule name as part of the component's styleOverrides property in a custom theme.

Source code

If you did not find the information in this page, consider having a look at the implementation of the component for more detail.