Chat - Slots & Composition

Replace individual subcomponents inside ChatBox with your own implementations using the slots and slotProps API.

ChatBox composes many themed subcomponents internally — message bubbles, the composer, the conversation list, date dividers, and more. The slots prop lets you swap any of them with your own component, while slotProps passes extra props to those components without replacing them.

Basic replacement

Pass a custom component to a named slot. Your component receives the same props that the default component would receive:

const CustomMessageContent = React.forwardRef(
  function CustomMessageContent(props, ref) {
    return (
      <ChatMessageContent
        ref={ref}
        {...props}
        slots={{ ...props.slots, bubble: MyBubble }}
      />
    );
  },
);

<ChatBox slots={{ messageContent: CustomMessageContent }} />;

Passing extra props with slotProps

Use slotProps to pass additional props to either the default or a custom slot component without replacing them:

<ChatBox
  slotProps={{
    conversationList: { 'aria-label': 'Chat threads' },
    composerInput: { placeholder: 'Ask anything...' },
    composerSendButton: { sx: { borderRadius: 6 } },
  }}
/>

Complete slot reference

Layout slots

Conversation slots

Message list slots

Composer slots

Indicator slots

Hiding a slot

Return null from a slot to remove it entirely, or use the features prop for common show/hide needs:

Feature flags and slot rendering

When a feature flag is set to false, the corresponding slot is not rendered at all — even if you provide a custom component via slots. The feature flag takes precedence:

{/* The custom button does not render because the feature is disabled */}
<ChatBox
  adapter={adapter}
  features={{ attachments: false }}
  slots={{ composerAttachButton: MyCustomButton }}  {/* ignored */}
/>

The autoScroll feature flag controls scroll behavior rather than slot visibility:

<ChatBox
  adapter={adapter}
  features={{
    autoScroll: { buffer: 300 }, // Custom threshold (default: 150px)
    // autoScroll: false,        // Disable auto-scrolling entirely
  }}
/>

To conditionally show a custom component, keep the feature flag enabled and handle visibility in your slot component instead.

slotProps reference

CSS classes

The chatBoxClasses utility object provides class name constants for CSS targeting:

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

// Available: chatBoxClasses.root, chatBoxClasses.layout,
//            chatBoxClasses.conversationsPane, chatBoxClasses.threadPane

TypeScript

Import the slot types for type-safe custom components:

import type { ChatBoxSlots, ChatBoxSlotProps } from '@mui/x-chat';

// Your custom slot component receives the same props as the default
const MyMessageContent: ChatBoxSlots['messageContent'] = (props) => {
  return <div className="custom-bubble" {...props} />;
};

// Type-safe slotProps
const mySlotProps: ChatBoxSlotProps = {
  composerInput: { placeholder: 'Type here...' },
  messageList: { sx: { p: 2 } },
};

Combining slots with theme overrides

Slots replace the component entirely, while theme styleOverrides adjust the default component's styles. You can use both together — for example, swap the message content component via a slot while applying global border-radius tweaks through the theme.

See also

• Styling for sx prop, theme overrides, and dark mode.

API

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

• <ChatBox />