XDSChatMessageList@xds/core · Chat

Usage

XDSChatMessageList is the scrollable container for chat messages. It renders children in a flex column with role="log" for accessibility, provides density context to child messages, and supports infinite scroll for loading older messages. Use it inside XDSChatLayout for full-page chat with auto-scroll and composer docking, or standalone for embedded message panels.

Best practices

GuidancePractices
DoCompose messages using MessageList > Message > Bubble for consistent sender-aware styling and density.
DoSet the density prop to control spacing globally — compact for sidebars, balanced for most views, spacious for long-form reading. Individual messages can override.
DoUse the group prop on bubbles (first, middle, last) when a single sender sends multiple consecutive messages — it tightens corner radius to visually connect them.
DoUse XDSChatSystemMessage with variant="divider" for date separators and default for inline status notices like joins, leaves, or topic changes.
DoPut name on the first bubble and metadata on the last bubble in a message so they align with the bubble's inline padding.
DoProvide an emptyState prop so new users see a clear prompt to start a conversation instead of a blank screen.
DoUse the ghost bubble variant for AI-style responses that show rich content like code blocks or markdown without a visible boundary.
Don'tDon't use XDSChatSystemMessage for sender content — it has no avatar, alignment, or bubble. Use XDSChatMessage with a sender role instead.
Don'tDon't put long or multi-line content in a system message — keep it to a single short sentence. If you need more, use a bubble or a card.
Don'tDon't nest XDSChatMessage inside another XDSChatMessage — each message is a standalone article element with its own sender context.
Don'tDon't apply a fixed height directly on the message list — wrap it in a sized container and let the list fill with flex: 1.
Don'tDon't mix filled and ghost bubble variants within the same sender's messages — pick one style per side and use it consistently.
Don'tDon't place metadata or names on both the bubble and the message wrapper — pick one based on whether the content has a bubble boundary.

Anatomy

ElementDescription
Message arearequiredScrollable region for messages. Renders children (typically XDSChatMessageList) in a flex column that pushes content to the bottom when the list is short.
Frosted glass dockrequiredSticky or fixed container at the bottom with a backdrop-blur layer. Houses the scroll button and composer.
Scroll-to-bottom buttonAppears when the user scrolls up or new messages arrive. Defaults to XDSChatLayoutScrollButton; pass null to hide or a custom element to override.
ComposerrequiredThe input area for sending messages, typically XDSChatComposer. Docked at the bottom inside the frosted glass layer.
Empty stateCentered placeholder shown when no messages exist. Use XDSEmptyState for a consistent look.
AvatarA sender avatar rendered beside the message. Typically XDSAvatar with size="small". Hidden for system messages.
NameSender name above the message body. Place on the bubble when using bubbles, or on the message wrapper for raw content.
ContentrequiredThe message body — one or more XDSChatMessageBubble elements, or any free-form ReactNode like images or tool calls.
MetadataTimestamp, delivery status, and footer actions below the message. Place on the last bubble or on the message wrapper.

Import

ts
import {XDSChatMessageList} from '@xds/core/Chat'

Props

PropTypeDescription
childrenrequired
ReactNodeMessage elements — typically XDSChatMessage or XDSChatSystemMessage.
emptyState
ReactNodeContent shown when the list has no messages.
scrollToTopAction
() => Promise<void>Async action fired when user scrolls to top. Use for loading older messages. Wrapped in useTransition — shows a spinner at the top while pending.
density
'compact' | 'balanced' | 'spacious' (default: 'balanced')Visual density — flows to child messages via context.

Examples

Common configurations, variations, and states.
ChatMessageList — DensitySide-by-side comparison of compact, balanced, and spacious densities. Use compact in sidebars or panels, balanced for most full-page chat, and spacious for long-form reading.
tsx
'use client';
​
import {
  XDSChatMessageList,
  XDSChatMessage,
  XDSChatMessageBubble,
} from '@xds/core/Chat';
import {XDSVStack} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
import {XDSAvatar} from '@xds/core/Avatar';
import * as stylex from '@stylexjs/stylex';
​
const styles = stylex.create({
  section: {
    flex: 1,
    minHeight: 0,
  },
});
​
const DENSITIES = ['compact', 'balanced', 'spacious'] as const;
​
const AVATAR_SIZE = {
  compact: 'xsmall' as const,
  balanced: 'small' as const,
  spacious: 'small' as const,
};
​
export default function ChatMessageListDensity() {
  return (
    <XDSVStack gap={4}>
      {DENSITIES.map(density => (
        <XDSVStack key={density} gap={2}>
          <XDSText type="supporting" color="secondary">
            {density.charAt(0).toUpperCase() + density.slice(1)}
          </XDSText>
          <XDSVStack xstyle={styles.section}>
            <XDSChatMessageList density={density}>
              <XDSChatMessage sender="user">
                <XDSChatMessageBubble>
                  How does density work?
                </XDSChatMessageBubble>
              </XDSChatMessage>
              <XDSChatMessage
                sender="assistant"
                avatar={<XDSAvatar name="Agent" size={AVATAR_SIZE[density]} />}>
                <XDSChatMessageBubble>
                  Density controls spacing at every level — gap between
                  messages, padding inside bubbles, and gap between child
                  elements.
                </XDSChatMessageBubble>
              </XDSChatMessage>
            </XDSChatMessageList>
          </XDSVStack>
        </XDSVStack>
      ))}
    </XDSVStack>
  );
}
ChatMessageList — Full FeaturedConversation showcasing system messages, multi-bubble grouping, markdown, code blocks, and metadata. Combines date dividers, ghost bubbles, grouped messages, and rich content in a single example.
tsx
'use client';
​
import {
  XDSChatMessageList,
  XDSChatMessage,
  XDSChatMessageBubble,
  XDSChatMessageMetadata,
  XDSChatSystemMessage,
} from '@xds/core/Chat';
import {XDSVStack, XDSHStack} from '@xds/core/Layout';
import {XDSAvatar} from '@xds/core/Avatar';
import {XDSMarkdown} from '@xds/core/Markdown';
import {XDSCodeBlock} from '@xds/core/CodeBlock';
import {XDSTimestamp} from '@xds/core/Timestamp';
import {XDSToken} from '@xds/core/Token';
import * as stylex from '@stylexjs/stylex';
​
const styles = stylex.create({
  container: {
    maxWidth: 600,
    justifyContent: 'center',
  },
});
​
export default function ChatMessageListFullFeatured() {
  return (
    <XDSVStack xstyle={styles.container}>
      <XDSChatMessageList>
        <XDSChatSystemMessage variant="divider">Today</XDSChatSystemMessage>
​
        <XDSChatMessage sender="user">
          <XDSHStack gap={2} wrap="wrap">
            <XDSToken label="useReducer.ts" />
            <XDSToken label="formState.ts" />
          </XDSHStack>
          <XDSChatMessageBubble
            metadata={
              <XDSChatMessageMetadata
                timestamp={
                  <XDSTimestamp value="2026-03-15T14:30:00" format="time" />
                }
                status="read"
              />
            }>
            Can you review these files?
          </XDSChatMessageBubble>
        </XDSChatMessage>
​
        <XDSChatMessage
          sender="assistant"
          avatar={<XDSAvatar name="Agent" size="small" />}>
          <XDSChatMessageBubble group="first">
            <XDSMarkdown density="compact">
              {`Sure! Here's the key pattern from **useReducer.ts**:`}
            </XDSMarkdown>
          </XDSChatMessageBubble>
          <XDSChatMessageBubble variant="ghost" group="middle">
            <XDSCodeBlock
              code={`const [state, dispatch] = useReducer(
  (state, action) => ({
    ...state,
    [action.field]: action.value,
  }),
  { name: '', email: '' }
);`}
              language="tsx"
            />
          </XDSChatMessageBubble>
          <XDSChatMessageBubble
            group="last"
            metadata={
              <XDSChatMessageMetadata
                timestamp={
                  <XDSTimestamp value="2026-03-15T14:30:30" format="time" />
                }
              />
            }>
            <XDSMarkdown density="compact">
              {`The reducer is **pure and easy to test** — pass in state and action, assert on the output.`}
            </XDSMarkdown>
          </XDSChatMessageBubble>
        </XDSChatMessage>
​
        <XDSChatSystemMessage>Agent shared a code snippet</XDSChatSystemMessage>
​
        <XDSChatMessage sender="user">
          <XDSChatMessageBubble
            metadata={
              <XDSChatMessageMetadata
                timestamp={
                  <XDSTimestamp value="2026-03-15T14:31:00" format="time" />
                }
                status="delivered"
              />
            }>
            That's clean, thanks!
          </XDSChatMessageBubble>
        </XDSChatMessage>
      </XDSChatMessageList>
    </XDSVStack>
  );
}

Showcase source

tsx
'use client';
​
import {
  XDSChatMessageList,
  XDSChatMessage,
  XDSChatMessageBubble,
  XDSChatMessageMetadata,
  XDSChatSystemMessage,
} from '@xds/core/Chat';
import {XDSVStack} from '@xds/core/Layout';
import {XDSTimestamp} from '@xds/core/Timestamp';
import * as stylex from '@stylexjs/stylex';
​
const styles = stylex.create({
  container: {
    maxWidth: 600,
    height: '100%',
  },
});
​
export default function ChatMessageListShowcase() {
  return (
    <XDSVStack xstyle={styles.container}>
      <XDSChatMessageList density="balanced">
        <XDSChatSystemMessage variant="divider">
          March 15, 2026
        </XDSChatSystemMessage>
​
        <XDSChatMessage sender="user">
          <XDSChatMessageBubble
            metadata={
              <XDSChatMessageMetadata
                timestamp={
                  <XDSTimestamp value="2026-03-15T14:30:00" format="time" />
                }
                status="read"
              />
            }>
            How should I structure a monorepo?
          </XDSChatMessageBubble>
        </XDSChatMessage>
​
        <XDSChatMessage sender="assistant">
          <XDSChatMessageBubble
            metadata={
              <XDSChatMessageMetadata
                timestamp={
                  <XDSTimestamp value="2026-03-15T14:30:15" format="time" />
                }
              />
            }>
            Use workspaces with a shared packages directory. Keep each package
            focused on a single concern.
          </XDSChatMessageBubble>
        </XDSChatMessage>
​
        <XDSChatMessage sender="user">
          <XDSChatMessageBubble
            metadata={
              <XDSChatMessageMetadata
                timestamp={
                  <XDSTimestamp value="2026-03-15T14:31:00" format="time" />
                }
                status="delivered"
              />
            }>
            Should I use Yarn or pnpm for that?
          </XDSChatMessageBubble>
        </XDSChatMessage>
      </XDSChatMessageList>
    </XDSVStack>
  );
}