XDS — Design System

ChatLayoutScrollButton@xds/core · XDSChatLayoutScrollButton v0.0.13

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.

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

Best practices

Guidance	Practices
Do	Compose messages using MessageList > Message > Bubble for consistent sender-aware styling and density.
Do	Set the density prop to control spacing globally — compact for sidebars, balanced for most views, spacious for long-form reading. Individual messages can override.
Do	Use the group prop on bubbles (first, middle, last) when a single sender sends multiple consecutive messages — it tightens corner radius to visually connect them.
Do	Use XDSChatSystemMessage with variant="divider" for date separators and default for inline status notices like joins, leaves, or topic changes.
Do	Put name on the first bubble and metadata on the last bubble in a message so they align with the bubble's inline padding.
Do	Provide an emptyState prop so new users see a clear prompt to start a conversation instead of a blank screen.
Do	Use the ghost bubble variant for AI-style responses that show rich content like code blocks or markdown without a visible boundary.
Don't	Don't use XDSChatSystemMessage for sender content — it has no avatar, alignment, or bubble. Use XDSChatMessage with a sender role instead.
Don't	Don'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't	Don't nest XDSChatMessage inside another XDSChatMessage — each message is a standalone article element with its own sender context.
Don't	Don'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't	Don't mix filled and ghost bubble variants within the same sender's messages — pick one style per side and use it consistently.
Don't	Don't place metadata or names on both the bubble and the message wrapper — pick one based on whether the content has a bubble boundary.

Examples

Common configurations, variations, and states.

ChatLayoutScrollButton — LabelsScroll button with different labels for context-specific notifications like new messages, unread replies, or a generic scroll prompt.

tsx
'use client';
import {XDSChatLayoutScrollButton} from '@xds/core/Chat';
import {XDSStack} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
export default function ChatLayoutScrollButtonLabels() {
  return (
    <XDSStack direction="vertical" gap={4}>
      <XDSText type="supporting" color="secondary">
        Labels expand the button to give context
      </XDSText>
      <XDSStack direction="vertical" gap={3}>
        <XDSChatLayoutScrollButton
          isVisible={true}
          onClick={() => {}}
        />
        <XDSChatLayoutScrollButton
          isVisible={true}
          label="New messages"
          onClick={() => {}}
        />
        <XDSChatLayoutScrollButton
          isVisible={true}
          label="3 unread replies"
          onClick={() => {}}
        />
      </XDSStack>
    </XDSStack>
  );
}

Showcase source

tsx
'use client';
import {XDSChatLayoutScrollButton} from '@xds/core/Chat';
import {XDSStack} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
export default function ChatLayoutScrollButtonStates() {
  return (
    <XDSStack direction="vertical" gap={4}>
      <XDSStack direction="vertical" gap={1}>
        <XDSText type="supporting" color="secondary">
          Hidden (user is at bottom)
        </XDSText>
        <XDSChatLayoutScrollButton
          isVisible={false}
          onClick={() => {}}
        />
      </XDSStack>
      <XDSStack direction="vertical" gap={1}>
        <XDSText type="supporting" color="secondary">
          Visible (user scrolled up)
        </XDSText>
        <XDSChatLayoutScrollButton
          isVisible={true}
          onClick={() => {}}
        />
      </XDSStack>
      <XDSStack direction="vertical" gap={1}>
        <XDSText type="supporting" color="secondary">
          Expanded with label (new messages arrived)
        </XDSText>
        <XDSChatLayoutScrollButton
          isVisible={true}
          label="New messages"
          onClick={() => {}}
        />
      </XDSStack>
    </XDSStack>
  );
}

Usage

import {XDSChatLayoutScrollButton} from '@xds/core/Chat'

Best practices

Guidance	Practices
Do	Compose messages using MessageList > Message > Bubble for consistent sender-aware styling and density.
Do	Set the density prop to control spacing globally — compact for sidebars, balanced for most views, spacious for long-form reading. Individual messages can override.
Do	Use the group prop on bubbles (first, middle, last) when a single sender sends multiple consecutive messages — it tightens corner radius to visually connect them.
Do	Use XDSChatSystemMessage with variant="divider" for date separators and default for inline status notices like joins, leaves, or topic changes.
Do	Put name on the first bubble and metadata on the last bubble in a message so they align with the bubble's inline padding.
Do	Provide an emptyState prop so new users see a clear prompt to start a conversation instead of a blank screen.
Do	Use the ghost bubble variant for AI-style responses that show rich content like code blocks or markdown without a visible boundary.
Don't	Don't use XDSChatSystemMessage for sender content — it has no avatar, alignment, or bubble. Use XDSChatMessage with a sender role instead.
Don't	Don'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't	Don't nest XDSChatMessage inside another XDSChatMessage — each message is a standalone article element with its own sender context.
Don't	Don'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't	Don't mix filled and ghost bubble variants within the same sender's messages — pick one style per side and use it consistently.
Don't	Don't place metadata or names on both the bubble and the message wrapper — pick one based on whether the content has a bubble boundary.

tsx

'use client'; import {XDSChatLayoutScrollButton} from '@xds/core/Chat'; import {XDSStack} from '@xds/core/Layout'; import {XDSText} from '@xds/core/Text'; export default function ChatLayoutScrollButtonLabels() { return ( <XDSStack direction="vertical" gap={4}> <XDSText type="supporting" color="secondary"> Labels expand the button to give context </XDSText> <XDSStack direction="vertical" gap={3}> <XDSChatLayoutScrollButton isVisible={true} onClick={() => {}} /> <XDSChatLayoutScrollButton isVisible={true} label="New messages" onClick={() => {}} /> <XDSChatLayoutScrollButton isVisible={true} label="3 unread replies" onClick={() => {}} /> </XDSStack> </XDSStack> ); }

tsx

'use client'; import {XDSChatLayoutScrollButton} from '@xds/core/Chat'; import {XDSStack} from '@xds/core/Layout'; import {XDSText} from '@xds/core/Text'; export default function ChatLayoutScrollButtonStates() { return ( <XDSStack direction="vertical" gap={4}> <XDSStack direction="vertical" gap={1}> <XDSText type="supporting" color="secondary"> Hidden (user is at bottom) </XDSText> <XDSChatLayoutScrollButton isVisible={false} onClick={() => {}} /> </XDSStack> <XDSStack direction="vertical" gap={1}> <XDSText type="supporting" color="secondary"> Visible (user scrolled up) </XDSText> <XDSChatLayoutScrollButton isVisible={true} onClick={() => {}} /> </XDSStack> <XDSStack direction="vertical" gap={1}> <XDSText type="supporting" color="secondary"> Expanded with label (new messages arrived) </XDSText> <XDSChatLayoutScrollButton isVisible={true} label="New messages" onClick={() => {}} /> </XDSStack> </XDSStack> ); }