Chat - Conversation list

Customize the conversation sidebar — from simple slot overrides to fully custom item renderers — using the Material UI conversation list components.

The conversation list is the sidebar that shows all available conversations and lets users switch between them. @mui/x-chat ships ChatConversationList, a single component with fully themed styled slots for every visual sub-region: the scroller, each item row, the avatar, the title, the preview line, the timestamp, and the unread badge.

The following demo shows a multi-conversation layout with the conversation list in action:

Component anatomy

ChatConversationList renders one row per conversation. The default row structure is:

ChatConversationList              ← scrolling listbox (role="listbox")
  [per conversation]
  item                            ← row container (role="option")
    itemAvatar                    ← 40×40 circular avatar
    itemContent                   ← flex column: title + preview
      title                       ← conversation name (bold when unread)
      preview                     ← last message text (caption, truncated)
    timestamp                     ← last-message time (caption, right-aligned)
    unreadBadge                   ← count badge (primary.main background)

All visual slots are owned by a single ChatConversationList instance. You do not need to compose subcomponents manually — instead you replace any slot through the slots prop directly on ChatConversationList.

Slot reference

Because the Material UI layer fills all slot defaults at instantiation, overriding a single slot only affects that region without disturbing the others.

ownerState and how state flows

The item and all its sub-slots receive an ownerState prop that carries the current row's interaction state alongside the full conversation object.

Item ownerState

The selected flag drives the row background (palette.action.selected). The unread flag drives bold title typography. The focused flag drives the focus-visible outline for keyboard accessibility.

Because the full conversation object is included, custom slot components can directly read fields such as conversation.title, conversation.metadata, conversation.unreadCount, and conversation.lastMessageAt without additional selectors.

Root ownerState

Overriding the avatar

Replace the avatar slot with a custom component to render initials or a status ring:

The ownerState prop arrives directly on the component because the Material UI layer passes it through slotProps using a function form. Destructure it before spreading ...props to avoid forwarding a non-standard attribute to the DOM.

Overriding the item content layout

Replace itemContent when you want to change the structural layout of the title and preview region — for example to add a participant count or an icon:

When you replace itemContent, the title and preview slots are no longer rendered (they are children of the default itemContent). Render any equivalent content directly inside your custom component.

Overriding the full item row

Replace the item slot to take full control of a row's layout while still benefiting from the built-in selection, keyboard navigation, and aria-selected wiring:

The role="option" and aria-selected attributes are set automatically before the slot renders, so they are present on the element even without the default styled item. Spread ...props to pass them through.

Styling without slot replacement

If the default row structure suits your product but you only need to change colors or typography, use theme component overrides instead of replacing slots:

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

const theme = createTheme({
  components: {
    MuiChatConversationList: {
      styleOverrides: {
        item: ({ ownerState }) => ({
          borderRadius: 8,
          marginInline: 4,
          ...(ownerState?.selected && {
            backgroundColor: 'var(--mui-palette-primary-main)',
            color: 'var(--mui-palette-primary-contrastText)',
          }),
        }),
        title: ({ ownerState }) => ({
          fontWeight: ownerState?.unread ? 700 : 400,
        }),
      },
    },
  },
});

Theme overrides apply globally across your application and are the lowest-friction option when you only need visual adjustments.

Controlling the list width

The conversation list width is driven by the scroller slot. Override it through slotProps:

<ChatConversationList
  slotProps={{
    scroller: { sx: { width: 320 } },
  }}
/>

Or set the CSS variable on a parent element to control the width from a layout level:

<Box sx={{ '--ChatBox-conversationListWidth': '320px' }}>
  <ChatConversationList />
</Box>

Full custom item renderer

The conversation object in ownerState lets you derive everything you need to render a rich row without additional data fetching or selectors. The following example builds a full item renderer that shows an avatar with initials, a bold title for unread conversations, a truncated preview, a human-readable timestamp, and a count badge:

Accessibility notes

The default list uses role="listbox" on the root and role="option" with aria-selected on each row. Roving focus is managed automatically: only one row is in the tab order at a time, and ArrowUp, ArrowDown, Home, End, and Enter are handled automatically.

Custom item slot components must forward all ...props to the DOM element they render so the role, aria-selected, and keyboard handler props are preserved. Failing to spread ...props breaks both keyboard navigation and screen-reader semantics.

Pass aria-label to the root through slotProps:

<ChatConversationList slotProps={{ root: { 'aria-label': 'Conversations' } }} />

See also

• Thread for the conversation thread surface and its composition model.
• Customization for the full slot and slotProps reference.
• Multi-conversation for a two-pane inbox demo using controlled state.

API

• ConversationListRoot
• ConversationListItem
• ConversationListItemAvatar
• ConversationListTitle
• ConversationListPreview
• ConversationListTimestamp
• ConversationListUnreadBadge

API

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

• <ConversationListItem />
• <ConversationListItemAvatar />
• <ConversationListPreview />
• <ConversationListRoot />
• <ConversationListTimestamp />
• <ConversationListTitle />
• <ConversationListUnreadBadge />