Message Scroller

A chat scroll container that anchors turns, opens saved transcripts, follows streamed responses, loads history without jumping, and jumps to any message.

New Chat

Demo is read only. Press send to send messages.

What Makes a Great Streaming Chat Experience

Building a chat interface used to be simple. You create an inverted list with an input. Type a message, it appends at the bottom. When a reply comes in, the list grows and scrolls. Done.

Streaming breaks that model. Messages arrive in chunks while you may still be reading, scrolling, or looking somewhere else entirely.

Now the challenge is preserving the reader’s place while the conversation keeps changing. Get that wrong and the experience feels jumpy: people are pulled to the bottom, lose context, and have to find their way back.

In practice, this comes down to scroll: when to follow, when to hold, and when to let the reader decide. A great streaming chat should:

Move only when the reader asked to move. If someone is reading, don’t pull them somewhere else. Auto-scroll should never be the default.
Follow only while they’re following. If they’re at the live edge, keep the stream in view. If they scroll away, leave them there.
Every interaction is a signal. Scrolling is not the only one. Selecting text, using the keyboard, opening a link, or searching should all stop the interface from moving.
Start a new turn near the top of the viewport. This gives the new turn somewhere it can be read from the beginning.
Then stream in the answer. The answer should grow into the screen, not immediately push everything away.
Keep part of the previous conversation in context. The prompt and reply should stay visually connected, and enough of the previous turn should remain visible so the reader knows where they are.
Let new content arrive offscreen. The conversation can keep streaming without changing what the reader is looking at.
Show what’s happening out of view. Make it clear when a response is still streaming or when new messages have arrived.
Make it easy to return to the latest reply. A “Jump to latest” action should bring the reader back and resume following.
Let people jump anywhere in the conversation. Long threads need message links, search, unread markers, and direct navigation.
Reopen where the reader left off. A saved conversation should open at the last meaningful turn. Often this is the last user message. Not the absolute bottom.
Keep the reader’s place when layout changes. Images load. Markdown expands. Code blocks render. Older messages appear above. None of that should make the reader lose their place.
Handle interruptions without stealing position. Stopping, retrying, regenerating, branching, or errors should not unexpectedly move the conversation.
Stay responsive in long threads. Streaming text, markdown, code, images, and long history should still feel responsive.
Be accessible without the noise. Keep the transcript navigable, preserve keyboard focus, and announce important events at a comfortable pace.

Never move the reader against their intent.

MessageScroller

MessageScroller is a chat transcript scroller built for these behaviors. MessageScroller.Provider owns the scroll state and transcript-row behavior: opening position, streamed output, new-turn anchoring, prepended history, visibility, and scroll controls. MessageScroller.Root is the styled frame that renders inside it.

MessageScroller is scoped to the scroll viewport. It does not own messages, AI state, transport, persistence, branching, or model state. Your product code stays focused on composing Message rows, Marker events, tools, attachments, and prompt inputs.

It gives you the scroll behavior that chat needs, without taking over the rest of the chat UI. And it stays fast, even in long conversations with rich markdown.

Installation

import { MessageScroller } from "@o/pipeline/experimental/components/chat/message-scroller";

Usage

import { Message } from "@o/pipeline/experimental/components/chat/message";
import { MessageScroller } from "@o/pipeline/experimental/components/chat/message-scroller";

<MessageScroller.Provider>
  <MessageScroller.Root>
    <MessageScroller.Viewport>
      <MessageScroller.Content>
        {messages.map((message) => (
          <MessageScroller.Item
            key={message.id}
            messageId={message.id}
            scrollAnchor={message.role === "user"}
          >
            <Message.Root />
          </MessageScroller.Item>
        ))}
      </MessageScroller.Content>
    </MessageScroller.Viewport>
    <MessageScroller.Button />
  </MessageScroller.Root>
</MessageScroller.Provider>

MessageScroller.Root fills its parent, so place it inside a height-constrained container.

<div className="flex h-screen flex-col">
  <MessageScroller.Provider>
    <MessageScroller.Root className="flex-1">
      {/* transcript */}
    </MessageScroller.Root>
  </MessageScroller.Provider>
</div>

Composition

<MessageScroller.Provider>
  <MessageScroller.Root>
    <MessageScroller.Viewport>
      <MessageScroller.Content>
        <MessageScroller.Item>
          {/* a message, marker, or row */}
        </MessageScroller.Item>
        <MessageScroller.Item />
        <MessageScroller.Item />
      </MessageScroller.Content>
    </MessageScroller.Viewport>
    <MessageScroller.Button />
  </MessageScroller.Root>
</MessageScroller.Provider>

MessageScroller.Provider — the headless root. Owns scroll state and the behavior props for opening position, auto-scroll, anchoring, scroll commands, and visibility tracking.
MessageScroller.Root — the styled frame. Lays out the viewport, content, and controls inside the provider.
MessageScroller.Viewport — the scrollable element. Receives native scroll events and preserves the visible row when older messages are prepended.
MessageScroller.Content — the transcript container. Holds the rows and provides the live-region defaults for new messages.
MessageScroller.Item — the transcript row boundary. Wrap every direct child of the content so the scroller can measure, anchor, preserve position, track visibility, and jump to it. An item can be a message, marker, typing indicator, separator, join/leave event, or “load earlier” row.
MessageScroller.Button — the scroll control. Scrolls to the start or end of the transcript and is inert until there is content in its direction.

Core Concepts

Anchoring Turns

A turn is the part of the conversation that starts a new exchange. In a simple AI chat, that is usually the user’s message and the assistant reply that follows.

An anchor is the row the viewport should treat as the start of that turn. Mark that row with scrollAnchor. When a new anchor is appended, the viewport moves it near the top and keeps a peek of the previous item above it, so the new turn does not feel detached from its context.

// This tells the scroller to anchor the user's message for the next turn.
<MessageScroller.Item
  messageId={message.id}
  scrollAnchor={message.role === "user"}
/>

Scroll anchors are not tied to message role. You can turn any row into an anchor: a user message, a system marker, a handoff event, or anything else that starts a meaningful turn. MessageScroller only needs to know which row should anchor the viewport.

In the following example, the user’s message is anchored. When you send a new message, the viewport anchors it near the top and appends the assistant reply below it. Toggle the anchor to the assistant’s message to see the difference.

Anchoring Turns

Toggle the anchor role, then send messages to compare where turns settle.

Group Chat

In a group chat, the turn boundary is more specific than “the user message”. It is often the message that asks the model to respond, or a marker like “Marcus joined the chat”. Typing indicators and history controls usually should not anchor.

Because anchoring is role-independent, you can anchor a Marker just as easily as a message.

<MessageScroller.Item messageId="marcus-joined" scrollAnchor>
  <Marker.Root variant="separator">
    <Marker.Content>Marcus joined the chat</Marker.Content>
  </Marker.Root>
</MessageScroller.Item>

Group Chat

@mary, the astrophage line keeps matching Venus energy output. Can you check my math?

Mary (Agent)

Yes. Confirmed. The curve points to a microorganism harvesting stellar energy and breeding near carbon dioxide. If @rocky agrees, this is the clue we need.

ping @rocky

When a user joins, a marker is created. scrollAnchor on the marker marks it as the next turn

Keeping Context Visible

When a new turn starts, it should still feel like part of the same continuous thread. scrollPreviousItemPeek keeps a slice of the previous item visible above the anchor, so the reader keeps their context instead of feeling like the conversation restarted on a blank page.

// Keep 64px of the previous turn visible above the newly anchored row.
<MessageScroller.Provider scrollPreviousItemPeek={64}>
  <MessageScroller.Root>{/* anchored turns */}</MessageScroller.Root>
</MessageScroller.Provider>

Adjust the peek amount in the example below to see how it affects the conversation.

Keeping Context Visible

I'm building a chat for our app and the scroll behavior is driving me nuts. Every time the AI streams a reply, the whole thread jumps around.

That's the classic streaming scroll problem. Wrap your message list in `MessageScroller` and turn on `autoScroll` — the viewport pins to the bottom as tokens arrive, so users always see the latest text land in place.

The important part: it only auto-scrolls while the reader is already at the bottom. The moment they scroll up to read something earlier, auto-scroll backs off and their position is preserved. You get smooth streaming without fighting the user's intent.

Adjust the peek preset and send. Observe the previous message peak

Following the Live Edge

When the reader is at the live edge, either because they stayed there or returned there, autoScroll keeps streamed replies in view as they grow. Scrolling away from the live edge releases the view, whether by wheel, touch, keyboard scroll keys, or dragging the scrollbar. An explicit message jump releases it too. New chunks can then arrive without moving the reader.

autoScroll composes with turn anchoring. When a new turn anchors near the top, the view stays put while the reply streams into the room below it. Once the reply fills the viewport, the reader is back at the live edge and follow-output takes over from the anchor.

<MessageScroller.Provider autoScroll>
  <MessageScroller.Root>{/* streamed turns */}</MessageScroller.Root>
</MessageScroller.Provider>

Streaming Messages

Streaming is simulated. `autoScroll` is enabled.

Calling scrollToEnd, or pressing MessageScroller.Button, re-engages follow-output when autoScroll is enabled, so a reader who scrolled away can return to the live edge and keep following. The root and viewport expose data-autoscrolling while that programmatic scroll to the latest message runs, so you can conditionally apply styles during the transition.

Opening Saved Threads

It can seem reasonable to reopen a saved thread at the absolute end of the transcript, but that often drops the reader into the conversation without enough context. A better default is "last-anchor": show the last meaningful turn, like the user’s latest message, with the reply below it.

That gives the reader an immediate place in the thread. They can see what they asked, where the answer starts, and continue from there without reconstructing the conversation from the bottom edge.

<MessageScroller.Provider defaultScrollPosition="last-anchor">
  <MessageScroller.Root>{/* transcript */}</MessageScroller.Root>
</MessageScroller.Provider>

Opening Position

This is the first message the user sent in the conversation.

Workspace creation rose 8%, but first invite completion only rose 2%.

This is the last message the user sent in the conversation.

Start with the invite step. Teams are creating workspaces but waiting to add collaborators.

Recommended follow-up:

1. Compare invite drop-off by account size. 2. Check whether users who skip invites still return within 24 hours. 3. Review the empty-state copy on the first project screen. 4. Segment activation by template, since template users may not need invites right away.

If that pattern holds, the next experiment should make collaboration useful earlier instead of prompting for invites harder.

Toggle the defaultScrollPosition to see where the transcript starts when you open the thread

"last-anchor" is keyed on scrollAnchor, not message role. If no anchor exists, or the last anchored turn already fits in the viewport, it falls back to "end".

Use "start" when you want to resume at the beginning of a conversation, or "end" when the absolute latest message is the right place to land.

Loading Earlier Messages

Loading earlier messages should not move the conversation the reader is already looking at. When older rows are prepended above the current transcript, MessageScroller.Viewport preserves the visible row so the reader stays in the same place while history loads above them.

This is enabled by default through preserveScrollOnPrepend.

Load History

Only the export queue worker changed. The deploy moved large CSV jobs onto the shared retry policy, which made each failed attempt hold a worker slot longer than before.

The app deploy did not include checkout, pricing, or billing API changes.

Do we need to roll back?

Not yet. Queue depth is recovering after we reduced retry concurrency, and the oldest pending job is now under five minutes old.

Keep rollback ready if the queue starts climbing again, but the current trend points toward recovery.

Keep watching for customer-visible issues.

I will watch the queue and support tags for another 15 minutes. I am tracking export failures, delayed download requests, and any support thread that mentions missing reports.

If those stay quiet through the next batch window, we can close this as an internal degradation.

End of Conversation

Click Load History to load the entire conversation

Use stable messageId values for message rows. That gives the scroller a specific row to preserve instead of guessing from whichever pixel happens to sit at the viewport edge.

Animating New Messages

MessageScroller.Item can be animated directly. Create a motion version of the item, keep messageId and scrollAnchor on it, and use transform and opacity for the entrance.

A common chat pattern is to animate the user’s message when it is sent, then let the assistant reply stream into a regular row below it. Start the user row below its final position so it feels like it rises from the live edge of the viewport.

const MotionMessageScrollerItem = motion.create(MessageScroller.Item);

Animation

Select an animation then click send to see it in action.

Avoid animating height, margin, or padding for row entrances; those changes can fight the scroller’s positioning work. If the reader prefers reduced motion, skip the entrance animation and keep the scroll behavior the same.

Jumping to Messages

Search results, permalinks, outline items, and toolbar buttons often need to drive the transcript from outside the message list. Use useMessageScroller for those controls. Because the hooks read from MessageScroller.Provider, they work in any component inside the provider, including controls rendered outside the MessageScroller.Root frame.

import { useMessageScroller } from "@o/pipeline/experimental/components/chat/message-scroller";

const { scrollToMessage, scrollToEnd, scrollToStart } = useMessageScroller();

Commands

We're seeing activation dip after workspace creation. Can you help me find the likely step?

The sharpest drop is between creating the workspace and inviting the first teammate.

Workspace creation is still healthy, but the invite step is where users pause. That suggests the product is asking for collaboration before the user has enough confidence in the workspace.

What should I compare before we change the onboarding flow?

Compare three cohorts:

1. Users who choose a template before inviting teammates. 2. Users who start from a blank workspace. 3. Users who skip invites and return within 24 hours.

If template users invite faster, the fix is probably better first-run guidance rather than a louder invite prompt.

Can you turn that into an experiment?

Yes. Create a variant that shows a short checklist after workspace creation:

- Pick a template. - Add one project detail. - Invite a teammate when the workspace has context.

Measure first invite completion, 24-hour return rate, and whether teams create a second project.

What's the risk if we delay the invite prompt?

The main risk is reducing team creation for accounts that already know who they want to invite.

To protect that path, keep the invite action visible in the header and only change the primary empty-state guidance. That gives confident teams a direct route without forcing uncertain users through the invite step too early.

Use the controls to jump to any message in the conversation.

scrollToMessage targets the messageId on MessageScroller.Item, so rows that need to be addressable should have stable ids. scrollToMessage returns false when the target is not mounted and cannot be queued.

scrollToMessage can queue a target before items exist, which covers client-resolved permalinks while the transcript mounts. After rows have mounted, a missing id returns false instead of starting a guessed retry loop. A true result means the scroll ran or was queued, not that the row is already in view.

Tracking the Reader’s Position

Use useMessageScrollerVisibility to track the reader’s position in the conversation. A common example is a table-of-contents or a jump menu that highlights the current anchored turn.

import { useMessageScrollerVisibility } from "@o/pipeline/experimental/components/chat/message-scroller";

const { currentAnchorId, visibleMessageIds } = useMessageScrollerVisibility();

Transcript Outline

Review the incident handoff and tell me what to read first.

Start with the summary and the impact section. The regression affected the upload queue, but the recovery path completed for every queued job.

What was the customer impact?

Impact was limited to delayed processing.

No records were dropped, and the reconciliation worker confirmed each retry batch. Support saw confusion from two customers, but there were no checkout or billing errors.

What actions are open?

Keep the retry window enabled until the next deploy, then add a queue-depth alert as the long-term fix.

The alert should fire on sustained queue growth, not a single short spike.

Give me the follow-up checklist.

After that, compare the queue recovery graph with the deploy timeline so the handoff shows exactly when processing returned to baseline. That makes it easier for support and engineering to answer the same customer questions without re-reading the whole incident thread.

I would also add a short owner note beside each follow-up item. The checklist is small, but ownership keeps the retry-window decision, alert tuning, and support macro from drifting into separate follow-up conversations.

Keep the retry window enabled until the next deploy, then add a queue-depth alert as the long-term fix.

The alert should fire on sustained queue growth, not a single short spike.

Open the outline to jump between anchored turns as you read.

currentAnchorId answers “where am I” by reporting the current anchored turn, and it stays set after that anchor scrolls above the viewport. visibleMessageIds answers “what is on screen”, in document order.

Visibility is pay-for-what-you-use. Tracking only runs while something subscribes to useMessageScrollerVisibility, and rows need a messageId to participate.

Reading Scroll State

Use useMessageScrollerScrollable when you need scroll state in JavaScript, such as a status indicator or a custom “jump to latest” control. It reports which edges the viewport can still scroll toward; “at the start/end” is the negation (!start / !end), and “scrollable at all” is start || end. For styling the scroller itself, prefer the data-scrollable attribute.

import { useMessageScrollerScrollable } from "@o/pipeline/experimental/components/chat/message-scroller";

const { start, end } = useMessageScrollerScrollable();

Scroll Status

Review scroll checkpoint 1.

Checkpoint 2 is synced. The scrollable hook updates as the viewport moves.

When the reader is at the first message, the footer should only point them down. Once they move into the middle of the transcript, it should explain that both directions are available.