React ConversationList component

Preview

const reply = "Two files need updated imports.";

<ConversationList>
  <Message from="user">
    <Message.Content>Which files break the workspace rules?</Message.Content>
  </Message>

Usage

Use when

Chat interfaces holding many messages
Transcripts that should follow new arrivals
Paging back through older message history
Runs of messages grouped day by day

Avoid when

Plain item lists with no chat context (use List)
A single message (use Message directly)
Layouts that never scroll

Implementation notes

Give the log a parent with a definite height; it fills it and scrolls
autoScroll="smart" follows only while the reader is at the end; away from it, new messages are counted under the log
Implement onScrollTop and set history while earlier messages load; the reader's place holds
ConversationList.Event marks a day break (date) or something that happened (a model switch)
Put ThinkingIndicator last while the reply has not started
Give new conversations an emptyState

Installation

pnpm add @usefragments/ui

The npm package stays managed by your package manager. Import styles once from @usefragments/ui/styles. See the installation guide for framework and theme setup.

Anatomy

Import ConversationList once, then compose its parts with dot notation.

ConversationList.Event

Examples

With Events

A day break and a model switch.

const yesterday = new Date(2026, 9, 3);

<ConversationList>
  <ConversationList.Event date={yesterday} />
  <Message from="user">
    <Message.Content>Check main.</Message.Content>

Thinking

The indicator sits last until the reply starts.

const waiting = true;
const messages = [<Message key="question" from="user"><Message.Content>Check main.</Message.Content></Message>];

<ConversationList>
  {messages}
  {waiting && <ThinkingIndicator label="Reading the request…" />}

Loading History

Earlier messages load at the top; the reader's place holds.

const loading = true;
const loadEarlier = () => {};
const messages = [<Message key="question" from="user"><Message.Content>Check main.</Message.Content></Message>];

<ConversationList onScrollTop={loadEarlier} history={loading ? "loading" : "idle"}>
  {messages}

History Failed

A failed load says so and offers Retry.

const loadEarlier = () => {};
const messages = [<Message key="question" from="user"><Message.Content>Check main.</Message.Content></Message>];

<ConversationList history="error" onRetryHistory={loadEarlier}>
  {messages}
</ConversationList>

Empty

A first-run state when there are no messages.

<ConversationList
  emptyState={<EmptyState><EmptyState.Title>Ask about your design system</EmptyState.Title></EmptyState>}
>
  {[]}
</ConversationList>

API reference

Component props
Prop	Type	Default	Description
`autoScroll`	`AutoScrollBehavior \| undefined`	`smart`	smart follows new content while the reader is at the end; false never moves the reader
`children`Required	`React.ReactNode`	Not set	Messages, events and the thinking indicator
`emptyState`	`React.ReactNode`	Not set	What shows when there are no messages
`Event.children`	`React.ReactNode`	Not set	What happened (a model switch, a joined user). Wins over `date`.
`Event.date`	`Date \| undefined`	Not set	A date for a day break; formatted as Today, Yesterday or the date.
`Event.format`	`((date: Date) => string) \| undefined`	Not set	Custom date format.
`history`	`ConversationHistory \| undefinedidleloadingerror`	`idle`	Where earlier messages stand: idle, loading (a status line) or error (an errbox with Retry)
`label`	`string \| undefined`	`Conversation`	Accessible name of the log
`onRetryHistory`	`(() => void) \| undefined`	Not set	Retry loading earlier messages after history=error
`onScrollTop`	`(() => void) \| undefined`	Not set	Called when the reader reaches the top, to load earlier messages
`onScroll`	`UIEventHandler<HTMLDivElement> \| undefined`	Not set	—

Accessibility

The log is role=log with a name and polite announcements
The scroller takes keyboard focus and draws its ring inside the edge
Loading history is a status; a failed load is an errbox with a labelled Retry
The jump button names what it does: N new messages or Jump to latest
Event hairlines are decorative; dates are time elements

MessagechildConversationList contains Message components
ThinkingIndicatorchildShow ThinkingIndicator at bottom while awaiting response
PromptsiblingTypically paired with Prompt for input

Next steps

Accessibility guidanceThe keyboard, focus and naming rules every component carries.
Every componentThe catalog, grouped by what each component does.