Skip to contentSkip to content
🚀 Influence MUI's 2026 roadmap! Take our latest Developer Survey

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

NameTypeDefaultDescription
adapter*{}-
activeConversationIdstring-
classesPartial-

Override or extend the styles applied to the component.

See CSS classes API below for more details.

composerValuestring-
conversationsArray<{ avatarUrl?: string, id: string, lastMessageAt?: string, metadata?: ChatConversationMetadata, participants?: Array<{ avatarUrl?: string, displayName?: string, id: string, isOnline?: bool, metadata?: ChatUserMetadata, role?: any
| any
| any }>, readState?: 'read'
| 'unread', subtitle?: string, title?: string, unreadCount?: number }>		-
currentUser{ avatarUrl?: string, displayName?: string, id: string, isOnline?: bool, metadata?: ChatUserMetadata, role?: 'assistant'
| 'system'
| 'user' }		-

The local user sending messages. If omitted, derived from members by finding the entry with role === 'user'.

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?: bool
| bool
| { acceptedMimeTypes?: Array<string>, maxFileCount?: number, maxFileSize?: number, onAttachmentReject?: func }, autoScroll?: bool
| bool
| { buffer?: number }, conversationHeader?: bool, helperText?: bool, scrollToBottom?: bool, suggestions?: bool }		-

Feature flags to enable or disable built-in ChatBox behaviours.

initialActiveConversationIdstring-

The initial active conversation ID when uncontrolled. Ignored after initialization and when activeConversationId is provided.

initialComposerValuestring-

The initial composer value when uncontrolled. Ignored after initialization and when composerValue is provided.

initialConversationsArray<{ avatarUrl?: string, id: string, lastMessageAt?: string, metadata?: ChatConversationMetadata, participants?: Array<{ avatarUrl?: string, displayName?: string, id: string, isOnline?: bool, metadata?: ChatUserMetadata, role?: any
| any
| any }>, readState?: 'read'
| 'unread', subtitle?: string, title?: string, unreadCount?: number }>		-

The initial conversations when uncontrolled. Ignored after initialization and when conversations is provided.

initialMessagesArray<{ author?: { avatarUrl?: string, displayName?: string, id: string, isOnline?: bool, metadata?: ChatUserMetadata, role?: 'assistant'
| 'system'
| 'user' }, conversationId?: string, createdAt?: string, editedAt?: string, id: string, metadata?: ChatMessageMetadata, parts: Array<ChatDynamicToolMessagePart
| ChatFileMessagePart
| ChatReasoningMessagePart
| ChatSourceDocumentMessagePart
| ChatSourceUrlMessagePart
| ChatStepStartMessagePart
| ChatTextMessagePart
| ChatToolMessagePart
| {}>, 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.

localeTextPartial-
membersArray<{ avatarUrl?: string, displayName?: string, id: string, isOnline?: bool, metadata?: ChatUserMetadata, role?: 'assistant'
| 'system'
| 'user' }>		-

All participants in the chat. The current (local) user is derived as the first member with role === 'user', unless currentUser is provided explicitly.

messagesArray<{ author?: { avatarUrl?: string, displayName?: string, id: string, isOnline?: bool, metadata?: ChatUserMetadata, role?: 'assistant'
| 'system'
| 'user' }, conversationId?: string, createdAt?: string, editedAt?: string, id: string, metadata?: ChatMessageMetadata, parts: Array<ChatDynamicToolMessagePart
| ChatFileMessagePart
| ChatReasoningMessagePart
| ChatSourceDocumentMessagePart
| ChatSourceUrlMessagePart
| ChatStepStartMessagePart
| ChatTextMessagePart
| ChatToolMessagePart
| {}>, role: 'assistant'
| 'system'
| 'user', status?: 'cancelled'
| 'error'
| 'pending'
| 'read'
| 'sending'
| 'sent'
| 'streaming', updatedAt?: string }>		-
onActiveConversationChangefunc-
Signature:function(conversationId: string | undefined) => void
    onComposerValueChangefunc-
    Signature:function(value: string) => void
      onConversationsChangefunc-
      Signature:function(conversations: Array<ChatConversation>) => void
        onDatafunc-
        Signature:function(part: ChatFallbackDataMessagePart<`data-${string}`>) => void | Promise<void>
          onErrorfunc-
          Signature:function(error: ChatError) => void
            onFinishfunc-
            Signature:function(payload: ChatOnFinishPayload) => void | Promise<void>
              onMessagesChangefunc-
              Signature:function(messages: Array<ChatMessage>) => void
                onToolCallfunc-
                Signature:function(payload: ChatOnToolCallPayload) => void | Promise<void>
                  partRenderers{ dynamic-tool?: func, file?: func, reasoning?: func, source-document?: func, source-url?: func, step-start?: func, text?: func, tool?: func }-
                  slotPropsChatBoxSlotProps-

                  The extra props for the slot components.

                  slotsPartial-

                  The components used for each slot inside the ChatBox.

                  See Slots API below for more details.

                  storeClassChatStoreConstructorChatStore

                  The store class to use for this provider.

                  streamFlushIntervalnumber16

                  Flush interval in milliseconds for batching rapid streaming deltas before applying them to the store.

                  suggestionsArray<string
                  | { label?: string, value: string }>                  		-

                  Prompt suggestions displayed in the empty state. Clicking a suggestion pre-fills the composer.

                  suggestionsAutoSubmitboolfalse

                  Whether clicking a suggestion automatically submits the message.

                  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 nameClass nameDefault componentDescription
                  composerAttachButtonOverride the composer attach button.
                  composerAttachmentListOverride the composer attachment list.
                  composerHelperTextOverride the composer helper text component.
                  composerInputOverride the composer textarea component.
                  composerRootOverride the composer (input) root component.
                  composerSendButtonOverride the composer send button.
                  composerToolbarOverride the composer toolbar.
                  conversationHeaderOverride the conversation header component.
                  conversationHeaderActionsOverride the conversation header actions component.
                  conversationHeaderInfoOverride the conversation header info wrapper (title + subtitle column).
                  conversationListOverride the conversation list component.
                  conversationsPane.MuiChatBox-conversationsPaneThe conversations pane container. Defaults to `div`.
                  conversationSubtitleOverride the conversation subtitle component.
                  conversationTitleOverride the conversation title component.
                  dateDividerOverride the date divider component.
                  layout.MuiChatBox-layoutThe layout element that arranges conversations + thread panes. Defaults to `div`.
                  messageActionsOverride the message actions component.
                  messageAvatarOverride the message avatar component.
                  messageContentOverride the message content (bubble) component.
                  messageGroupOverride the message group component.
                  messageListOverride the message list component.
                  messageMetaOverride the message meta component.
                  messageRootOverride the message root component for each message.
                  root.MuiChatBox-rootThe outermost container element. Defaults to `div`.
                  scrollToBottomOverride the scroll-to-bottom affordance component.
                  suggestionsOverride the prompt suggestions container component.
                  threadPane.MuiChatBox-threadPaneThe thread pane container. Defaults to `div`.
                  typingIndicatorOverride the typing indicator component.
                  unreadMarkerOverride the unread marker component.

                  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 nameRule nameDescription
                  .MuiChatBox-conversationsPaneconversationsPaneStyles applied to the conversations pane element.
                  .MuiChatBox-layoutlayoutStyles applied to the layout element.
                  .MuiChatBox-rootrootStyles applied to the root element.
                  .MuiChatBox-threadPanethreadPaneStyles applied to the thread pane element.

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

                  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.