Chat - Unread marker

Highlight messages that arrived while users were away with an inline divider in the chat thread.

Overview

The unread marker appears inline in the message list when the active conversation has unread messages. The marker is positioned at the first unread message and is removed once the conversation's unreadCount reaches 0 (the user has caught up). It is an opt-in feature: nothing renders until you enable it, and you can also embed the component directly in custom layouts. For date-based thread separators, see the Date divider page.

Enabling the unread marker

Pass features={{ unreadMarker: true }} to ChatBox (or to a standalone ChatMessageList) to render the marker at the unread boundary:

<ChatBox adapter={adapter} features={{ unreadMarker: true }} />

Once enabled, customize the rendered component with the unreadMarker slot, or forward props through slotProps.unreadMarker. The label text is localizable through the unreadMarkerLabel locale key.

How the marker is positioned

The marker's position is derived from the active conversation's read state, not from message flags:

When conversation.unreadCount is greater than 0, the marker renders above the first unread message — at index messages.length - unreadCount (clamped to the first message when unreadCount exceeds the message count).
When unreadCount is not set (or is 0) and conversation.readState is 'unread', the marker renders above the first message.
Otherwise (the user has caught up), nothing renders — even with features.unreadMarker enabled.

See the Read receipts page for how unreadCount and readState are set and updated.

Standalone usage

ChatUnreadMarker can be embedded directly in a custom message layout. Render it once per message and pass the required messageId prop — the component identifies the message it is anchored above, and renders only when that message sits at the unread boundary (it returns null everywhere else).

MUI Assistant

Message 1

You

Message 2

MUI Assistant

Message 3

New messages

You

Message 4

MUI Assistant

Message 5

Edit code

<ScopedChat
  conversations={[conversation]}
  messages={messages}
  activeConversationId={CONVERSATION_ID}
>
  <Box sx={{ width: '100%' }}>
    {messages.map((message) => (
      <React.Fragment key={message.id}>
        <ChatUnreadMarker messageId={message.id} />
        <MessageBubble messageId={message.id} />
      </React.Fragment>
    ))}
  </Box>
</ScopedChat>

<ScopedChat
  conversations={[conversation]}
  messages={messages}
  activeConversationId={CONVERSATION_ID}
>
  <Box sx={{ width: '100%' }}>
    {messages.map((message) => (
      <React.Fragment key={message.id}>
        <ChatUnreadMarker messageId={message.id} />
        <MessageBubble messageId={message.id} />
      </React.Fragment>
    ))}
  </Box>
</ScopedChat>

Press Enter to start editing

Accessibility

The marker root renders with role="separator", so assistive technology announces it as a thread divider rather than message content. The visible label (default "New messages") is the announced text — override it through the label prop or the unreadMarkerLabel locale key to localize the announcement. The rendered root carries a data-has-boundary="true" attribute.

For the full keyboard navigation and screen-reader model of the message list, see the Message list accessibility section.

Interactive playground

The demo below shows the unread marker rendering above the first unread message:

ChatUnreadMarker

Divider rendered when a message sits at the unread boundary.

MUI Assistant

Message 1

Message 2

New messages

Message 3

Message 4

fixture (thread shape)

message count4

boundary index2

Where the marker is rendered — drives messageId prop.

props

labelstring

Empty = locale default (New messages).

API

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

<ChatUnreadMarker />