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

ChatProvider API

API reference docs for the React ChatProvider component. Learn about the props, CSS, and other APIs of this exported module.

Demos

Import

import { ChatProvider } from '@mui/x-chat-headless';
// or
import { ChatProvider } from '@mui/x-chat';

Learn about the difference by reading this guide on minimizing bundle size.

Props

NameTypeDefaultDescription
adapter*{}-
activeConversationIdstring-
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'.

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.

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 }-
                  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.

                  The component cannot hold a ref.

                  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.