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.
classes	object	-	Override or extend the styles applied to the component. See CSS classes API below for more details.
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.
estimatedItemSize	number	84	The estimated height of a row in pixels, used until the row is measured.
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.
getItemKey	func	(id) => id	Returns the React key of a row. Signature:`function(id: string, index: number) => React.Key` `id` The id of the message. `index` The index of the row.
items	Array<string>	-	The ids of the messages to render, in order.
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.
slotProps	object	{}	The props used for each component slot.
slots	object	{}	Overridable component slots. See Slots API below for more details.
sx	Array<func \| object \| bool> \| func \| object	-	The system prop that allows defining system overrides as well as additional CSS styles. See the `sx` page for more details.

The component cannot hold a ref.

Slots

Slot name	Default component	Description
messageList	ScrollRoot (Base UI ScrollArea.Root wrapper); a styled 'div' in `ChatMessageList`	The component that renders the message list.
messageListScroller	ScrollViewport (Base UI ScrollArea.Viewport wrapper), or 'div' when `slots.messageList` is set; a styled 'div' in `ChatMessageList`	The component that renders the message list scroller.
messageListContent	`'div'`	The component that renders the message list content.
messageListOverlay	`'div'`	The component that renders the message list overlay.
messageListScrollbar	ScrollScrollbar (Base UI ScrollArea.Scrollbar wrapper); not rendered when `slots.messageList` is set, as in `ChatMessageList`	The component that renders the message list scrollbar.
messageListScrollbarThumb	ScrollThumb (Base UI ScrollArea.Thumb wrapper); not rendered when `slots.messageList` is set, as in `ChatMessageList`	The component that renders the message list scrollbar thumb.
messageListStatus	`'div'`	The visually-hidden `role="status"` element announcing streaming transitions ("Assistant is responding" / "Response complete") to screen readers. Pass `null`-rendering component to silence the announcements.
dateDivider	`ChatDateDivider`	The date separator rendered between message groups. Only rendered when `features.dateDivider` is enabled. Pass `null` to hide it.
unreadMarker	`ChatUnreadMarker`	The "new messages" marker. Only rendered when `features.unreadMarker` is enabled. Pass `null` to hide it.
messageGroup	`'div'`	The per-author group wrapper around consecutive messages.
streamingIndicator	`ChatStreamingIndicator, wrapped in an assistant row with an avatar while waiting for the response to start`	The animated dots shown while an assistant response is in flight: as a trailing row while waiting for the response to start, then inside the assistant bubble while it streams. Controlled by `features.streamingIndicator` (`'auto'` by default). Pass `null` to hide it.
messageRoot	`'div'`	Styled root of `<ChatMessage>` (wrapper-only); the default avatar/content/meta tree still renders inside it.
messageAvatar	`ChatMessageAvatar`	Avatar component. Pass `null` to hide the avatar entirely and drop the reserved avatar grid track.
messageContent	`ChatMessageContent`	The message bubble component.
messageMeta	`ChatMessageMeta`	External meta (compact variant). Pass `null` to hide.
messageInlineMeta	`ChatMessageInlineMeta`	Inline meta rendered inside the bubble (default variant). Pass `null` to hide.
messageError	`ChatMessageError`	Error card shown under the bubble when the message status is `error`. Pass `null` to hide the error surface entirely (no component is mounted).
messageActions	An actions row with only the `extraActions` from `slotProps.messageActions`, if any.	Actions row component (receives `{ messageId }`). Pass `null` to hide actions entirely; omit to render only the declarative `extraActions` from `slotProps.messageActions` if provided.
messageAuthorName	`'div'`	Author name label rendered by the group wrapper (default variant: above the bubble; compact variant: inside the message grid). Pass `null` to hide.

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.