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, helperText?: bool, scrollToBottom?: bool, suggestions?: bool } | - | Feature flags to enable or disable built-in ChatBox behaviours. |
| 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<{ state?: 'done' | 'streaming', text: string, type: 'text' } | { state?: 'done' | 'streaming', text: string, type: 'reasoning' } | { filename?: string, mediaType: string, type: 'file', url: string } | { sourceId: string, title?: string, type: 'source-url', url: string } | { sourceId: string, text?: string, title?: string, type: 'source-document' } | { data: any, id?: string, transient?: bool, type: object } | { type: 'step-start' } | { toolInvocation: { approval?: object, 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' } | { toolInvocation: { approval?: object, 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' }>, role: 'assistant' | 'system' | 'user', status?: 'cancelled' | 'error' | 'pending' | 'read' | 'sending' | 'sent' | 'streaming', updatedAt?: string }> | - | The initial messages when uncontrolled. Ignored after initialization and when |
| members | Array<{ avatarUrl?: string, displayName?: string, id: string, isOnline?: bool, metadata?: object, role?: 'assistant' | 'system' | 'user' }> | - | All participants in the chat. The current (local) user is derived as the first member with |
| slotProps | object | - | The extra props for the slot components. |
| slots | object | - | The components used for each slot inside the ChatBox. 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 container element. Defaults to div. | |
| layout | .MuiChatBox-layout | The layout element that arranges conversations + thread panes. Defaults to div. | |
| conversationsPane | .MuiChatBox-conversationsPane | The conversations pane container. Defaults to div. | |
| threadPane | .MuiChatBox-threadPane | The thread pane container. Defaults to div. | |
| conversationList | Override the conversation list component. | ||
| conversationHeader | Override the conversation header component. | ||
| conversationTitle | Override the conversation title component. | ||
| conversationSubtitle | Override the conversation subtitle component. | ||
| conversationHeaderInfo | Override the conversation header info wrapper (title + subtitle column). | ||
| conversationHeaderActions | Override the conversation header actions component. | ||
| messageList | Override the message list component. | ||
| messageRoot | Override the message root component for each message. | ||
| messageAvatar | Override the message avatar component. | ||
| messageContent | Override the message content (bubble) component. | ||
| messageMeta | Override the message meta component. | ||
| messageActions | Override the message actions component. | ||
| messageGroup | Override the message group component. | ||
| dateDivider | Override the date divider component. | ||
| composerRoot | Override the composer (input) root component. | ||
| composerInput | Override the composer textarea component. | ||
| composerSendButton | Override the composer send button. | ||
| composerAttachButton | Override the composer attach button. | ||
| composerAttachmentList | Override the composer attachment list. | ||
| composerToolbar | Override the composer toolbar. | ||
| composerHelperText | Override the composer helper text component. | ||
| typingIndicator | Override the typing indicator component. | ||
| unreadMarker | Override the unread marker component. | ||
| scrollToBottom | Override the scroll-to-bottom affordance component. | ||
| suggestions | Override the prompt suggestions container component. |
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.