ChatRoot API

API reference docs for the React ChatRoot 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 { ChatRoot } from '@mui/x-chat-headless/chat';
// or
import { ChatRoot } from '@mui/x-chat-headless';
// or
import { ChatRoot } from '@mui/x-chat';

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

Props

Name	Type	Default	Description
adapter*	{}	-
activeConversationId	string	-
composerValue	string	-
conversations	Array<{ 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'	-	The vertical spacing density of chat messages. When provided, wraps descendant components with `ChatDensityProvider`. - `'compact'` – Reduced vertical spacing between messages. - `'standard'` – Default spacing. - `'comfortable'` – Increased vertical spacing between messages.
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?: 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.
initialMessages	Array<{ 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.
localeText	Partial	-
members	Array<{ 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.
messages	Array<{ 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 }>	-
onActiveConversationChange	func	-	Signature:`function(conversationId: string \| undefined) => void`
onComposerValueChange	func	-	Signature:`function(value: string) => void`
onConversationsChange	func	-	Signature:`function(conversations: Array<ChatConversation>) => void`
onData	func	-	Signature:function(part: ChatFallbackDataMessagePart<`data-${string}`>) => void \| Promise<void>
onError	func	-	Signature:`function(error: ChatError) => void`
onFinish	func	-	Signature:`function(payload: ChatOnFinishPayload) => void \| Promise<void>`
onMessagesChange	func	-	Signature:`function(messages: Array<ChatMessage>) => void`
onToolCall	func	-	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 }	-
slotProps	ChatRootSlotProps	-
slots	Partial	-	See Slots API below for more details.
storeClass	ChatStoreConstructor	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.
variant	'compact' \| 'default'	-	The visual layout variant of the chat. When provided, wraps descendant components with `ChatVariantProvider` so message and conversation components can respond to the variant. - `'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

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.