Chat - Quickstart

Install the Chat package and start building React chat interfaces.

Installation

Install the Chat package:

npm install @mui/x-chat

Peer dependencies

Material UI

The Chat package has a peer dependency on @mui/material. If you're not already using it, install it now:

npm install @mui/material @emotion/react @emotion/styled

React

react and react-dom are also peer dependencies:

"peerDependencies": {
  "react": "^17.0.0 || ^18.0.0 || ^19.0.0",
  "react-dom": "^17.0.0 || ^18.0.0 || ^19.0.0"
},

Import ChatBox and wire it to an adapter. The adapter implements sendMessage, which returns the assistant's reply as a stream of response chunks. For streaming UIs and createAiSdkAdapter, see Streaming.

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

Render the component

The example below uses the built-in createEchoAdapter so it works directly in the docs. In your app, replace it with an adapter that calls your API.

Assistant

Hello! Send a message to see a response.

Edit code

'use client';
import { ChatBox, createEchoAdapter } from '@mui/x-chat';

const CONVERSATION_ID = 'quickstart';

const initialConversations = [{ id: CONVERSATION_ID, title: 'Assistant' }];

const initialMessages = [
  {
    id: 'welcome',
    conversationId: CONVERSATION_ID,
    role: 'assistant' as const,
    status: 'sent' as const,
    parts: [
      { type: 'text' as const, text: 'Hello! Send a message to see a response.' },
    ],
  },
];

const adapter = createEchoAdapter();

export default function RenderChatBox() {
  return (
    <ChatBox
      adapter={adapter}
      initialConversations={initialConversations}
      initialActiveConversationId={CONVERSATION_ID}
      initialMessages={initialMessages}
      // ChatBox fills its container — give it an explicit height in your layout.
      sx={{
        height: 500,
        border: '1px solid',
        borderColor: 'divider',
        borderRadius: 1,
      }}
    />
  );
}

'use client';
import { ChatBox, createEchoAdapter } from '@mui/x-chat';

const CONVERSATION_ID = 'quickstart';

const initialConversations = [{ id: CONVERSATION_ID, title: 'Assistant' }];

const initialMessages = [
  {
    id: 'welcome',
    conversationId: CONVERSATION_ID,
    role: 'assistant' as const,
    status: 'sent' as const,
    parts: [
      { type: 'text' as const, text: 'Hello! Send a message to see a response.' },
    ],
  },
];

const adapter = createEchoAdapter();

export default function RenderChatBox() {
  return (
    <ChatBox
      adapter={adapter}
      initialConversations={initialConversations}
      initialActiveConversationId={CONVERSATION_ID}
      initialMessages={initialMessages}
      // ChatBox fills its container — give it an explicit height in your layout.
      sx={{
        height: 500,
        border: '1px solid',
        borderColor: 'divider',
        borderRadius: 1,
      }}
    />
  );
}

Press Enter to start editing

ChatBox renders a full chat surface—conversation header, message list, and composer—in a single component. See Components for the full anatomy. Enable the built-in conversation list explicitly with features={{ conversationList: true }} when you want an inbox-style layout. The list only renders once at least one conversation exists (for example via initialConversations), so enabling the flag on an empty chat shows no sidebar. All visual styles are derived from your active Material UI theme.

Component questions

Which component handles the composer?

Alice Chen

Which component should I use for the message input area?

MUI Assistant

The composer is handled by the ChatBox automatically. You can override it with slots.composer.

Alice Chen

And what about slotProps for passing sx to the input?

See Conversation list for the full feature documentation.

Only adapter is required—it must implement sendMessage. initialMessages, initialConversations, and initialActiveConversationId are optional conveniences that pre-populate chat state on first render—the demo's welcome bubble comes from initialMessages. If features={{ conversationList: true }} is enabled, the same conversation data also feeds the built-in conversation list. Every other prop is optional.

Theme integration

ChatBox reads palette, typography, shape, and spacing from the closest ThemeProvider. No additional configuration is needed.

User message bubbles use palette.primary.main as the background color
Assistant bubbles use palette.grey[100] in light mode and palette.grey[800] in dark mode
typography.body2 governs message text
shape.borderRadius controls bubble rounding
palette.divider is used for borders and separators

Wrapping ChatBox in a ThemeProvider with custom values is enough to retheme the entire surface. See Look and feel—Theme component overrides for details.

TypeScript theme augmentation

To get autocomplete for style overrides in createTheme, import the augmentation side-effect:

import { createTheme } from '@mui/material/styles';
import type {} from '@mui/x-chat/themeAugmentation';

const theme = createTheme({
  components: {
    MuiChatBox: {
      styleOverrides: {
        root: {
          // your overrides
        },
      },
    },
  },
});

Next steps

Overview — what the Chat package covers and how it's organized
Components — every component the package ships
ChatBox — the full ChatBox feature walkthrough
Adapters — connect the chat to your own API

API

ChatBox

<ChatBox />