ChatBox API
API reference docs for the React ChatBox component. Learn about the props, CSS, and other APIs of this exported module.
Demos
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 of the native component are also available.
| Name | Type | Default | Description |
|---|---|---|---|
| classes | object | - | Override or extend the styles applied to the component. See CSS classes API below for more details. |
| currentUser | { avatarUrl?: string, displayName?: string, id: string, isOnline?: bool, metadata?: object, role?: 'assistant' | 'system' | 'user' } | - | The local user sending messages. If omitted, derived from |
| density | 'comfortable' | 'compact' | 'standard' | 'standard' | The vertical spacing density of chat 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 |
| getMessageAuthorDisplayName | func | (message) => message.author?.displayName | Used to determine the display name for a given message author. Falls back to |
| 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 |
| initialActiveConversationId | string | - | The initial active conversation ID when uncontrolled. Ignored after initialization and when |
| initialComposerValue | string | - | The initial composer value when uncontrolled. Ignored after initialization and when |
| 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 |
| 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 |
| 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 | { overlay?: number, split?: number } | - | Container-width breakpoints used when |
| 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. |
| 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 | object | - | The components used for each slot inside the ChatBox. Keys are flat and prefixed by area: 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. |
| variant | 'compact' | 'default' | 'default' | The visual layout variant of the chat. - |
| Slot name | Class name | Default component | Description |
|---|---|---|---|
| root | .MuiChatBox-root | The outermost ChatBox container element. | |
| layout | .MuiChatBox-layout | Wrapper that arranges the conversations pane and the thread pane. | |
| conversationsPane | .MuiChatBox-conversationsPane | Container for the conversation-list sidebar (or drawer on narrow widths). | |
| threadPane | .MuiChatBox-threadPane | Container for the active thread — the message list plus the composer. | |
| conversationRoot | Styled root of <ChatConversation> (wrapper-only); the default header, message list and composer continue to render inside it. | ||
| conversationList | The conversation-list sidebar component. | ||
| conversationHeader | The header bar rendered above the message list. | ||
| conversationHeaderInfo | The title + subtitle group inside the header. | ||
| conversationTitle | The conversation title element. | ||
| conversationSubtitle | The conversation subtitle element (participants, status, etc.). | ||
| conversationHeaderActions | The actions area on the trailing side of the header. | ||
| messageList | 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. | ||
| messageGroup | The per-author group wrapper around consecutive messages. | ||
| dateDivider | The date separator rendered between message groups. Only rendered when features.dateDivider is enabled. Pass null to hide it. | ||
| unreadMarker | The "new messages" marker. Only rendered when features.unreadMarker is enabled. Pass null to hide it. | ||
| streamingIndicator | 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 | Styled root of <ChatMessage> (wrapper-only); the default avatar/content/meta tree still renders inside it. | ||
| messageAvatar | Avatar component. Pass null to hide the avatar entirely and drop the reserved avatar grid track. | ||
| messageContent | The message bubble component. | ||
| messageMeta | External meta (compact variant). Pass null to hide. | ||
| messageInlineMeta | Inline meta rendered inside the bubble (default variant). Pass null to hide. | ||
| messageError | 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 | Actions row component (receives { messageId }). Pass null to hide actions entirely; omit to render only the declarative extraActions from slotProps.messageActions if provided. | ||
| messageAuthorName | Author name label rendered by the group wrapper (default variant: above the bubble; compact variant: inside the message grid). Pass null to hide. | ||
| composerRoot | Styled root of <ChatComposer> (wrapper-only); the default attach/input/send/ toolbar render inside it. | ||
| composerInput | The auto-resizing text input. | ||
| composerSendButton | Send button. Pass null to hide it; the form still submits on Enter. | ||
| composerAttachButton | 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 | The pending-attachment preview list. | ||
| composerToolbar | The composer toolbar (button row). | ||
| composerHelperText | The helper / disclaimer text below the input. | ||
| typingIndicator | The animated typing indicator shown while the assistant responds. | ||
| scrollToBottom | The floating scroll-to-bottom button. | ||
| suggestions | The prompt-suggestion chips. | ||
| emptyState | 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.