ChatBox API

API reference docs for the React ChatBox 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 { ChatBox } from '@mui/x-chat/ChatBox';
// or
import { ChatBox } 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
adapter*	{ addToolApprovalResponse?: func, listConversations?: func, listMessages?: func, loadMore?: func, markRead?: func, reconnectToStream?: func, regenerate?: func, sendMessage: func, setTyping?: func, stop?: func, subscribe?: func }	-	The adapter that connects the chat to your backend.
activeConversationId	string	-	The id of the active conversation. Use with `onActiveConversationChange` to control it.
children	node	-	The content of the component.
classes	object	-	Override or extend the styles applied to the component. See CSS classes API below for more details.
composerValue	string	-	The value of the composer. Use with `onComposerValueChange` to control it.
conversations	Array<{ avatarUrl?: string, id: string, lastMessageAt?: string, metadata?: object, participants?: Array<{ avatarUrl?: string, displayName?: string, id: string, isOnline?: bool, metadata?: object, role?: 'assistant' \| 'system' \| 'user' }>, readState?: 'read' \| 'unread', subtitle?: string, title?: string, unreadCount?: number }>	-	The conversations. Use with `onConversationsChange` to control them.
currentUser	{ avatarUrl?: string, displayName?: string, id: string, isOnline?: bool, metadata?: object, role?: 'assistant' \| 'system' \| 'user' }	-	The local user sending messages. If omitted, derived from `members` by finding the entry with `role === 'user'`. Also used to enrich message authors when a rendered message resolves to `currentUser.id`.
density	'comfortable' \| 'compact' \| 'standard'	'standard'	The vertical spacing density of chat messages. - `'compact'` – Reduced vertical spacing between messages. - `'standard'` – Default spacing. - `'comfortable'` – Increased vertical spacing between messages.
features	{ attachments?: { acceptedMimeTypes?: Array<string>, maxFileCount?: number, maxFileSize?: number, onAttachmentReject?: func } \| bool, autoScroll?: { buffer?: number } \| bool, conversationHeader?: bool, conversationList?: bool, dateDivider?: bool, helperText?: bool, scrollToBottom?: bool, streamingIndicator?: 'auto' \| bool, suggestions?: bool, typingSignal?: bool, unreadMarker?: bool }	-	Feature flags to enable or disable built-in ChatBox behaviours.
getMessageAuthorAvatarUrl	func	(message) => message.author?.avatarUrl	Used to determine the avatar URL for a given message author. Falls back to `message.author?.avatarUrl`, then to the matched member's `avatarUrl`.
getMessageAuthorDisplayName	func	(message) => message.author?.displayName	Used to determine the display name for a given message author. Falls back to `message.author?.displayName`, then to the matched member's `displayName`.
getMessageAuthorId	func	(message) => message.author?.id	Used to determine the author id for a given message. The resolved id is used to match message authors against `currentUser`, `members`, and active conversation participants.
initialActiveConversationId	string	-	The initial active conversation ID when uncontrolled. Ignored after initialization and when `activeConversationId` is provided.
initialComposerValue	string	-	The initial composer value when uncontrolled. Ignored after initialization and when `composerValue` is provided.
initialConversations	Array<{ avatarUrl?: string, id: string, lastMessageAt?: string, metadata?: object, participants?: Array<{ avatarUrl?: string, displayName?: string, id: string, isOnline?: bool, metadata?: object, role?: 'assistant' \| 'system' \| 'user' }>, readState?: 'read' \| 'unread', subtitle?: string, title?: string, unreadCount?: number }>	-	The initial conversations when uncontrolled. Ignored after initialization and when `conversations` is provided.
initialMessages	Array<{ author?: { avatarUrl?: string, displayName?: string, id: string, isOnline?: bool, metadata?: object, role?: 'assistant' \| 'system' \| 'user' }, conversationId?: string, createdAt?: string, editedAt?: string, id: string, metadata?: object, parts: Array<{ data: any, id?: string, transient?: bool, type: object } \| { filename?: string, mediaType: string, type: 'file', url: string } \| { sourceId: string, text?: string, title?: string, type: 'source-document' } \| { sourceId: string, title?: string, type: 'source-url', url: string } \| { state?: 'done' \| 'streaming', text: string, type: 'reasoning' } \| { state?: 'done' \| 'streaming', text: string, type: 'text' } \| { toolInvocation: { approval?: object, approvalId?: string, callProviderMetadata?: object, errorText?: string, input?: any, output?: any, preliminary?: bool, providerExecuted?: bool, state: 'approval-requested' \| 'approval-responded' \| 'input-available' \| 'input-streaming' \| 'output-available' \| 'output-denied' \| 'output-error', title?: string, toolCallId: string, toolName: string }, type: 'dynamic-tool' } \| { toolInvocation: { approval?: object, approvalId?: string, callProviderMetadata?: object, errorText?: string, input?: any, output?: any, preliminary?: bool, providerExecuted?: bool, state: 'approval-requested' \| 'approval-responded' \| 'input-available' \| 'input-streaming' \| 'output-available' \| 'output-denied' \| 'output-error', title?: string, toolCallId: string, toolName: string }, type: 'tool' } \| { type: 'step-start' }>, role: 'assistant' \| 'system' \| 'user', status?: 'cancelled' \| 'error' \| 'pending' \| 'read' \| 'sending' \| 'sent' \| 'streaming', updatedAt?: string }>	-	The initial messages when uncontrolled. Ignored after initialization and when `messages` is provided.
layoutMode	'overlay' \| 'split' \| 'standard'	-	Forces the responsive layout mode instead of deriving it from the container width. When omitted, ChatBox chooses the mode automatically using `layoutModeBreakpoints`.
layoutModeBreakpoints	{ overlay?: number, split?: number }	-	Container-width breakpoints used when `layoutMode` is not provided.
localeText	object	-	The props used for the locale text slot.
members	Array<{ avatarUrl?: string, displayName?: string, id: string, isOnline?: bool, metadata?: object, role?: 'assistant' \| 'system' \| 'user' }>	-	Known chat participants. Used to derive the local user / assistant user when explicit props are omitted, and to enrich message authors by resolved author id at render time.
messages	Array<{ author?: { avatarUrl?: string, displayName?: string, id: string, isOnline?: bool, metadata?: object, role?: 'assistant' \| 'system' \| 'user' }, conversationId?: string, createdAt?: string, editedAt?: string, id: string, metadata?: object, parts: Array<{ data: any, id?: string, transient?: bool, type: object } \| { filename?: string, mediaType: string, type: 'file', url: string } \| { sourceId: string, text?: string, title?: string, type: 'source-document' } \| { sourceId: string, title?: string, type: 'source-url', url: string } \| { state?: 'done' \| 'streaming', text: string, type: 'reasoning' } \| { state?: 'done' \| 'streaming', text: string, type: 'text' } \| { toolInvocation: { approval?: object, approvalId?: string, callProviderMetadata?: object, errorText?: string, input?: any, output?: any, preliminary?: bool, providerExecuted?: bool, state: 'approval-requested' \| 'approval-responded' \| 'input-available' \| 'input-streaming' \| 'output-available' \| 'output-denied' \| 'output-error', title?: string, toolCallId: string, toolName: string }, type: 'dynamic-tool' } \| { toolInvocation: { approval?: object, approvalId?: string, callProviderMetadata?: object, errorText?: string, input?: any, output?: any, preliminary?: bool, providerExecuted?: bool, state: 'approval-requested' \| 'approval-responded' \| 'input-available' \| 'input-streaming' \| 'output-available' \| 'output-denied' \| 'output-error', title?: string, toolCallId: string, toolName: string }, type: 'tool' } \| { type: 'step-start' }>, role: 'assistant' \| 'system' \| 'user', status?: 'cancelled' \| 'error' \| 'pending' \| 'read' \| 'sending' \| 'sent' \| 'streaming', updatedAt?: string }>	-	The messages of the active conversation. Use with `onMessagesChange` to control them.
onActiveConversationChange	func	-	Callback fired when the active conversation changes. Signature:`function(conversationId: string \| undefined) => void` `conversationId` The id of the new active conversation.
onComposerValueChange	func	-	Callback fired when the composer value changes. Signature:`function(value: string) => void` `value` The new composer value.
onConversationsChange	func	-	Callback fired when the conversations change. Signature:`function(conversations: Array<ChatConversation>) => void` `conversations` The new conversations.
onData	func	-	Callback fired when a data part is received. Signature:`function(part: ChatDataMessagePart) => void` `part` The data part.
onError	func	-	Callback fired when an error occurs. Signature:`function(error: ChatError) => void` `error` The error.
onFinish	func	-	Callback fired when the assistant finishes a response, including when it is aborted, disconnected, or fails. Signature:`function(payload: ChatOnFinishPayload) => void` `payload` The final message and how the response ended.
onMessagesChange	func	-	Callback fired when the messages change. Signature:`function(messages: Array<ChatMessage>) => void` `messages` The new messages.
onToolCall	func	-	Callback fired when the assistant calls a tool. Signature:`function(payload: ChatOnToolCallPayload) => void` `payload` The tool call.
partRenderers	{ dynamic-tool?: func, file?: func, reasoning?: func, source-document?: func, source-url?: func, step-start?: func, text?: func, tool?: func }	-	Custom renderers for message parts, by part type.
roleDisplayNames	{ assistant?: string, system?: string, user?: string }	-	Locale-driven fallback labels for messages without explicit author information.
slotProps	object	-	Props forwarded to each slot. Mirrors the flat keys of `slots`.
slots	object	-	The components used for each slot inside the ChatBox. Keys are flat and prefixed by area: - Layout — `root`, `layout`, `conversationsPane`, `threadPane`. - Conversation — `conversationRoot`, `conversationList`, `conversationHeader`, `conversationHeaderInfo`, `conversationTitle`, `conversationSubtitle`, `conversationHeaderActions`. - Message list — `messageList`, `messageGroup`, `dateDivider`, `unreadMarker`, `streamingIndicator`. The divider slots render only when the matching `features.dateDivider` / `features.unreadMarker` flag is enabled; the streaming indicator renders by default (`features.streamingIndicator: 'auto'`) and accepts `null` to hide it. - Message — `messageRoot`, `messageAvatar`, `messageContent`, `messageMeta`, `messageInlineMeta`, `messageError`, `messageActions`, `messageAuthorName`. Pass `null` to a presentational slot (`messageAvatar`, `messageMeta`, `messageInlineMeta`, `messageActions`, `messageAuthorName`) to hide it and collapse the surrounding layout. - Composer — `composerRoot`, `composerInput`, `composerSendButton`, `composerAttachButton`, `composerAttachmentList`, `composerToolbar`, `composerHelperText`. Pass `null` to `composerSendButton` / `composerAttachButton` to hide the button. - Widgets — `typingIndicator`, `scrollToBottom`, `suggestions`, `emptyState`. `*Root` slots (`conversationRoot`, `messageRoot`, `composerRoot`) are wrapper-only: they swap the styled element while the default children still render inside. See Slots API below for more details.
storeClass	func	ChatStore	The store class to use for this provider.
streamFlushInterval	number	16	Flush interval in milliseconds for batching rapid streaming deltas before applying them to the store.
suggestions	Array<{ label?: string, value: string } \| string>	-	Prompt suggestions displayed in the empty state. Clicking a suggestion pre-fills the composer.
suggestionsAutoSubmit	bool	false	Whether clicking a suggestion automatically submits the message.
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.
variant	'compact' \| 'default'	'default'	The visual layout variant of the chat. - `'default'` – Standard layout with avatars, individual timestamps, and full spacing. - `'compact'` – Messenger-style layout: no avatars, author + timestamp in group header, tighter spacing.

The component cannot hold a ref.

Slots

Slot name	Class name	Default component	Description
root	.MuiChatBox-root	`'div'`	The outermost `ChatBox` container element.
layout	.MuiChatBox-layout	`'div'`	Wrapper that arranges the conversations pane and the thread pane.
conversationsPane	.MuiChatBox-conversationsPane	`'div'`	Container for the conversation-list sidebar (or drawer on narrow widths).
threadPane	.MuiChatBox-threadPane	`'div'`	Container for the active thread — the message list plus the composer.
conversationRoot		`'div'`	Styled root of `<ChatConversation>` (wrapper-only); the default header, message list and composer continue to render inside it.
conversationList		`ChatConversationList`	The conversation-list sidebar component.
conversationHeader		`ChatConversationHeader`	The header bar rendered above the message list.
conversationHeaderInfo		`ChatConversationHeaderInfo`	The title + subtitle group inside the header.
conversationTitle		`ChatConversationTitle`	The conversation title element.
conversationSubtitle		`ChatConversationSubtitle`	The conversation subtitle element (participants, status, etc.).
conversationHeaderActions		`ChatConversationHeaderActions`	The actions area on the trailing side of the header.
messageList		`'div'`	Styled scrollable root element of `<ChatMessageList>` (wrapper-only). The default message rows render inside it, so a plain element such as `'section'` wraps the list rather than replacing it.
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.
composerRoot		`'form'`	Styled root of `<ChatComposer>` (wrapper-only); the default attach/input/send/ toolbar render inside it.
composerInput		`ChatComposerTextArea`	The auto-resizing text input.
composerSendButton		`ChatComposerSendButton`	Send button. Pass `null` to hide it; the form still submits on Enter.
composerAttachButton		`ChatComposerAttachButton`	Attach button. Pass `null` to hide just the button while keeping the rest of the attachment pipeline (drag/drop, paste). Use `features.attachments: false` to disable attachments entirely.
composerAttachmentList		`ChatComposerAttachmentList`	The pending-attachment preview list.
composerToolbar		`ChatComposerToolbar`	The composer toolbar (button row).
composerHelperText		`ChatComposerHelperText`	The helper / disclaimer text below the input.
typingIndicator		`null`	The animated typing indicator shown while the assistant responds.
scrollToBottom		`ChatScrollToBottomAffordance`	The floating scroll-to-bottom button.
suggestions		`ChatSuggestions`	The prompt-suggestion chips.
emptyState		`The built-in empty state, or the suggestions when there are some.`	Custom content rendered when the thread has no messages.

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.