Chat - ChatBox

The all-in-one component that renders a complete chat surface with a single import.

Overview

ChatBox is the fastest way to add a chat interface to your application. It creates a ChatProvider internally and composes every themed subcomponent — conversation list, thread header, message list, and composer — into a ready-to-use surface:

import { ChatBox } from '@mui/x-chat';

<ChatBox adapter={adapter} sx={{ height: 500 }} />;

All visual styles are derived from your active Material UI theme. No additional configuration is needed — ChatBox reads palette, typography, shape, and spacing from the closest ThemeProvider.

ChatBox vs. ChatProvider

ChatBox (all-in-one)

ChatBox is the right choice when you want a complete chat surface with minimal setup. It creates a ChatProvider internally, so all hooks work inside any component rendered as a child or descendant of ChatBox:

ChatProvider (custom layout)

When you need full control over the layout — for example, placing the conversation list in a sidebar and the thread in a main content area — use ChatProvider directly and compose the pieces yourself:

Feature flags

ChatBox accepts a features prop that toggles built-in capabilities on or off:

<ChatBox
  adapter={adapter}
  features={{
    attachments: false, // hide the attach button
    helperText: false, // hide the helper text
    scrollToBottom: false, // disable scroll-to-bottom affordance
    autoScroll: { buffer: 300 }, // custom auto-scroll threshold
  }}
/>

Feature flags let you progressively enable functionality without replacing slots or restructuring the component tree.

Controlled and uncontrolled state

ChatBox supports both controlled and uncontrolled patterns for every piece of state. These props are forwarded to the internal ChatProvider.

Messages

{
  /* Uncontrolled — internal store owns the messages */
}
<ChatBox adapter={adapter} initialMessages={initialMessages} />;

{
  /* Controlled — you own the messages array */
}
<ChatBox adapter={adapter} messages={messages} onMessagesChange={setMessages} />;

Conversations

{
  /* Uncontrolled */
}
<ChatBox
  adapter={adapter}
  initialConversations={conversations}
  initialActiveConversationId="conv-1"
/>;

{
  /* Controlled */
}
<ChatBox
  adapter={adapter}
  conversations={conversations}
  onConversationsChange={setConversations}
  activeConversationId={activeId}
  onActiveConversationChange={setActiveId}
/>;

Composer value

{
  /* Uncontrolled */
}
<ChatBox adapter={adapter} initialComposerValue="Hello" />;

{
  /* Controlled */
}
<ChatBox
  adapter={adapter}
  composerValue={composerValue}
  onComposerValueChange={setComposerValue}
/>;

You can mix controlled and uncontrolled state freely. For example, control the active conversation while letting messages be managed internally.

Multiple independent instances

Each ChatBox creates its own isolated store. To render multiple independent chat surfaces side by side, use separate ChatBox instances:

API

See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.

• <ChatBox />