Chat - Conversation

Pair a message list and composer into a single scrollable conversation surface.

Overview

ChatConversation is the mid-level layout primitive that pairs a ChatMessageList with a ChatComposer inside a single scrollable surface. Use it when you want full control of the conversation layout without wiring the scroll and composer interplay manually.

If you also need conversation switching, history, or read receipts, use ChatBox instead.

ChatConversation must be rendered inside a ChatProvider: the title, subtitle, and message list all read the active conversation from the Chat state. Appearance is controlled by the surrounding variant and density providers — see Variants and density and State and store.

Anatomy

ChatConversation is a compound component: you compose its children explicitly. A fully assembled conversation looks like this:

<ChatConversation>
  <ChatConversationHeader>
    <ChatConversationHeaderInfo>
      <ChatConversationTitle />
      <ChatConversationSubtitle />
    </ChatConversationHeaderInfo>
    <ChatConversationHeaderActions>{/* header buttons */}</ChatConversationHeaderActions>
  </ChatConversationHeader>
  <ChatMessageList renderItem={...} />
  <ChatComposer />
</ChatConversation>

ChatConversationHeader — the bar pinned at the top of the surface; the message list scrolls beneath it.
ChatConversationHeaderInfo — groups the title and subtitle on the left side of the header.
ChatConversationTitle / ChatConversationSubtitle — render the active conversation's title and subtitle from the Chat state; no props needed.
ChatConversationHeaderActions — hosts action buttons on the right side of the header.
ChatMessageList and ChatComposer fill the remaining space: the list scrolls, the composer stays pinned to the bottom.

All parts are optional — omit the header for a bare thread, or the composer for a read-only view. ChatConversation is also the "thread" pane of Layout: when rendered inside ChatLayout, it is recognized automatically and placed in the thread region. See Conversation header for header customization in depth.

ChatConversation has no behavior props of its own — beyond standard styling and slot props (className, sx, classes, slots, slotProps), you configure it entirely through composition and the surrounding Chat providers.

Basic usage

The demo below wires ChatConversation to a ChatProvider with a demo adapter. The title and subtitle come from the active conversation; send a message to see the list scroll and the echo reply arrive.

Material UI chat

Styled with your active MUI theme

MUI Assistant

Hello! I am styled using your active Material UI theme. Try sending a message.

You

Great — the bubble colors come from palette.primary and the typography from the theme.

Edit code

'use client';
import * as React from 'react';
import Box from '@mui/material/Box';
import IconButton from '@mui/material/IconButton';
import {
  ChatComposer,
  ChatConversation,
  ChatConversationHeader,
  ChatConversationHeaderActions,
  ChatConversationHeaderInfo,
  ChatConversationSubtitle,
  ChatConversationTitle,
  ChatMessageGroup,
  ChatMessageList,
} from '@mui/x-chat';
import { ChatProvider } from '@mui/x-chat/headless';
import { createEchoAdapter } from 'docs/data/chat/material/examples/shared/demoUtils';
import {
  minimalConversation,
  minimalMessages,
} from 'docs/data/chat/material/examples/shared/demoData';

const adapter = createEchoAdapter({
  respond: (text) =>
    `Received: "${text}". This thread is rendered by a single ChatConversation.`,
});

function MoreIcon() {
  return (
    <svg
      viewBox="0 0 24 24"
      fill="currentColor"
      aria-hidden="true"
      style={{ width: '1em', height: '1em' }}
    >
      <path d="M12 8c1.1 0 2-.9 2-2s-.9-2-2-2-2 .9-2 2 .9 2 2 2zm0 2c-1.1 0-2 .9-2 2s.9 2 2 2 2-.9 2-2-.9-2-2-2zm0 6c-1.1 0-2 .9-2 2s.9 2 2 2 2-.9 2-2-.9-2-2-2z" />
    </svg>
  );
}

export default function ConversationBasicStandalone() {
  const renderItem = React.useCallback(
    (params: { id: string }) => (
      <ChatMessageGroup key={params.id} messageId={params.id} />
    ),
    [],
  );

  return (
    <ChatProvider
      adapter={adapter}
      initialActiveConversationId={minimalConversation.id}
      initialConversations={[minimalConversation]}
      initialMessages={minimalMessages}
    >
      <Box
        sx={{
          height: 460,
          display: 'flex',
          overflow: 'hidden',
        }}
      >
        <ChatConversation>
          <ChatConversationHeader>
            <ChatConversationHeaderInfo>
              <ChatConversationTitle />
              <ChatConversationSubtitle />
            </ChatConversationHeaderInfo>
            <ChatConversationHeaderActions>
              <IconButton size="small" aria-label="Conversation options">
                <MoreIcon />
              </IconButton>
            </ChatConversationHeaderActions>
          </ChatConversationHeader>
          <ChatMessageList renderItem={renderItem} />
          <ChatComposer />
        </ChatConversation>
      </Box>
    </ChatProvider>
  );
}

'use client';
import * as React from 'react';
import Box from '@mui/material/Box';
import IconButton from '@mui/material/IconButton';
import {
  ChatComposer,
  ChatConversation,
  ChatConversationHeader,
  ChatConversationHeaderActions,
  ChatConversationHeaderInfo,
  ChatConversationSubtitle,
  ChatConversationTitle,
  ChatMessageGroup,
  ChatMessageList,
} from '@mui/x-chat';
import { ChatProvider } from '@mui/x-chat/headless';
import { createEchoAdapter } from 'docs/data/chat/material/examples/shared/demoUtils';
import {
  minimalConversation,
  minimalMessages,
} from 'docs/data/chat/material/examples/shared/demoData';

const adapter = createEchoAdapter({
  respond: (text) =>
    `Received: "${text}". This thread is rendered by a single ChatConversation.`,
});

function MoreIcon() {
  return (
    <svg
      viewBox="0 0 24 24"
      fill="currentColor"
      aria-hidden="true"
      style={{ width: '1em', height: '1em' }}
    >
      <path d="M12 8c1.1 0 2-.9 2-2s-.9-2-2-2-2 .9-2 2 .9 2 2 2zm0 2c-1.1 0-2 .9-2 2s.9 2 2 2 2-.9 2-2-.9-2-2-2zm0 6c-1.1 0-2 .9-2 2s.9 2 2 2 2-.9 2-2-.9-2-2-2z" />
    </svg>
  );
}

export default function ConversationBasicStandalone() {
  const renderItem = React.useCallback(
    (params: { id: string }) => (
      <ChatMessageGroup key={params.id} messageId={params.id} />
    ),
    [],
  );

  return (
    <ChatProvider
      adapter={adapter}
      initialActiveConversationId={minimalConversation.id}
      initialConversations={[minimalConversation]}
      initialMessages={minimalMessages}
    >
      <Box
        sx={{
          height: 460,
          display: 'flex',
          overflow: 'hidden',
        }}
      >
        <ChatConversation>
          <ChatConversationHeader>
            <ChatConversationHeaderInfo>
              <ChatConversationTitle />
              <ChatConversationSubtitle />
            </ChatConversationHeaderInfo>
            <ChatConversationHeaderActions>
              <IconButton size="small" aria-label="Conversation options">
                <MoreIcon />
              </IconButton>
            </ChatConversationHeaderActions>
          </ChatConversationHeader>
          <ChatMessageList renderItem={renderItem} />
          <ChatComposer />
        </ChatConversation>
      </Box>
    </ChatProvider>
  );
}

Press Enter to start editing

Interactive playground

The demo below lets you toggle whether the header and composer are rendered, and switch the surrounding variant and density:

ChatConversation (single thread shell)

Wrapper that hosts the header, list and composer for one conversation.

Styling questions

Theming MuiChatComposer

Alice Chen

Kicking off the design review thread.

MUI Assistant

Here are the three areas I want to flag.

header spacing 2) bubble radius 3) timestamp position

You

Picking this up today — radius first.

MUI Assistant

Sounds good. The default is shape.borderRadius * 2.

Chrome provider

ChatChrome.variantenum · 2

Set on the ChatVariantProvider — not on ChatConversation.

defaultcompact

ChatChrome.densityenum · 3

Set on the ChatDensityProvider — not on ChatConversation.

compactstandardcomfortable

Composition

render header

Render <ChatConversationHeader> as a child.

render composer

Render <ChatComposer> as a child.

API

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

<ChatConversation />