Chat - Headless messages

Compose chat message rows from grouping helpers, message subcomponents, and default part renderers.

The demo below shows a grouped message timeline composed from MessageGroup, Message.Root, and the default subparts:

Grouped timeline

Author and time-window grouping

Alice Chen

I reviewed the incident summary and grouped the first remediation steps.

Sent

The access token mismatch explains the initial deployment confusion.

Sent

Alice Chen

Nine minutes later, the customer confirmed the reset worked.

Sent

You

Let us fold that into the public timeline so support can reuse the steps.

Sent

Also add a note about why we keep message grouping separate from the data model.

Sent

MUI Guide

Done. The grouping window is now a local presentation choice inside the recipe.

Message surface primitives

The message surface is built from:

MessageGroup
Message.Root
Message.Avatar
Message.Content
Message.Meta
Message.Actions

Grouping consecutive messages

MessageGroup is the default row-level composition helper for threaded chats. It derives the previous and next message, then decides whether the current message starts or ends a visual group:

<MessageGroup groupingWindowMs={300_000} index={index} messageId={id} />

Grouping is based on:

Author identity.
Author role fallback when no explicit author id exists.
An adjustable grouping window in milliseconds.

MessageGroup exposes isFirst and isLast grouping state without manual row bookkeeping.

Grouping stays close to the row composition instead of leaking into application code, which is especially helpful when a thread mixes authored messages, assistant responses, and sparse metadata.

Resolving messages by id

Message.Root resolves a message by id and exposes owner state such as:

role
status
streaming
error
isGrouped

That owner state powers slot-based styling for user versus assistant messages, streaming states, and grouped rows.

Message.Root is the main bridge between state-driven message identity and the leaf subcomponents that render avatars, message bodies, metadata, and actions.

Default row stack

The most common message composition inside a group is:

Message.Avatar
Message.Content
Message.Meta
Message.Actions (optional).

MessageGroup can render this default stack for you, or you can provide custom children for a different row layout:

<MessageGroup index={index} messageId={id}>
  <Message.Root messageId={id}>
    <Message.Avatar />
    <Message.Content />
    <Message.Meta />
    <Message.Actions />
  </Message.Root>
</MessageGroup>

This pattern keeps grouping logic and row layout close together while still allowing subpart-level slot replacement.

Default message-part renderers

The headless package also exports helpers for common message parts:

getDefaultMessagePartRenderer()
renderDefaultTextPart()
renderDefaultReasoningPart()
renderDefaultToolPart()
renderDefaultDynamicToolPart()
renderDefaultFilePart()
renderDefaultSourceUrlPart()
renderDefaultSourceDocumentPart()
renderDefaultStepStartPart()
renderDefaultDataPart()

Use these helpers to keep the default rendering for most part types and selectively replace only one or two:

function renderPart(part: ChatMessagePart, message: ChatMessage, index: number) {
  if (part.type === 'reasoning') {
    return <CustomReasoningPanel part={part} />;
  }

  const renderer = getDefaultMessagePartRenderer(part);

  return renderer ? renderer({ part, message, index }) : null;
}

The helpers cover text, reasoning, tool parts, files, sources, step boundaries, and data-* parts. This makes them a good fit for progressive customization instead of full renderer rewrites.

When to replace message rendering

Use the default helpers when:

The structural message model is correct.
Only certain part types need a custom presentation.

Rebuild more of the message surface when:

The row layout is completely different.
Message actions need a different placement model.
Grouped and ungrouped messages need distinct markup.

API

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