Message Scroller for React Aria

A streamed reply grows while people are still reading. The scroller holds a new turn near the top, follows the reply only while the reader stays at the bottom, and keeps their place when older messages load above.

Use it for a chat or an assistant transcript. A Scroll Area is enough for a finished log read from the top. The scrolling comes from @shadcn/react, and in React the jump button is a React Aria button.

Installation

Anatomy

MessageScrollerProvider
└── MessageScroller
    ├── MessageScrollerViewport
    │   └── MessageScrollerContent
    │       └── MessageScrollerItem
    └── MessageScrollerButton

Usage

import {
  MessageScroller, MessageScrollerButton, MessageScrollerContent,
  MessageScrollerItem, MessageScrollerProvider, MessageScrollerViewport,
} from "@/components/ui/message-scroller";

<MessageScrollerProvider>
  <MessageScroller>
    <MessageScrollerViewport>
      <MessageScrollerContent>
        <MessageScrollerItem messageId="question" scrollAnchor>
          {/* the user's message */}
        </MessageScrollerItem>
        <MessageScrollerItem messageId="answer">
          {/* the reply */}
        </MessageScrollerItem>
      </MessageScrollerContent>
    </MessageScrollerViewport>
    <MessageScrollerButton />
  </MessageScroller>
</MessageScrollerProvider>

MessageScroller fills its parent, so put it in a container with a fixed height.

<div className="flex h-screen flex-col">
  <MessageScrollerProvider>
    <MessageScroller className="min-h-0 flex-1">
      {/* viewport, content, button */}
    </MessageScroller>
  </MessageScrollerProvider>
</div>

MessageScrollerProvider renders nothing and owns the scroll state. It takes autoScroll (off), defaultScrollPosition (end, or start and last-anchor, applied once), scrollPreviousItemPeek (64), scrollMargin (0) and scrollEdgeThreshold (8, how close to an edge still counts as at it). MessageScroller is the frame, and like the viewport it mirrors the state as data-scrollable (start, end, both, or absent when everything fits), data-autoscrolling and data-pending-scroll. MessageScrollerViewport is the element that scrolls, and preserveScrollOnPrepend (on) keeps the visible row in place when rows are added above. MessageScrollerContent holds the rows and is the live region, and spacerClassName styles the spacer it adds to make room under an anchored turn. Wrap every row in MessageScrollerItem, with a messageId and, on a row that starts a turn, scrollAnchor. A row can be a message, a marker, a typing indicator or a load-more row, and the wrapper is what lets the scroller measure it, anchor it and jump to it. MessageScrollerButton scrolls toward its direction (end, or start) with behavior (smooth), and stays inert, with data-active="false", until there is something that way.

Hooks

import {
  useMessageScroller,
  useMessageScrollerScrollable,
  useMessageScrollerVisibility,
} from "@/components/ui/message-scroller";

const { scrollToMessage, scrollToEnd, scrollToStart } = useMessageScroller();
const { start, end } = useMessageScrollerScrollable();
const { currentAnchorId, visibleMessageIds } = useMessageScrollerVisibility();

The three hooks read MessageScrollerProvider, so they work in any component under it, including a toolbar outside the MessageScroller frame. The commands take align (start by default, or center, end, nearest), behavior (auto by default) and scrollMargin. They return false when they can't run: the viewport isn't mounted, or the row isn't and can't be queued. scrollToMessage can queue an id before the rows mount, for a permalink. Once rows exist, an unknown id returns false instead of retrying, and true means the scroll ran or was queued, not that the row is in view yet.

start and end say which edges the viewport can still scroll toward: at the top is !start, at the bottom is !end. end stays false while auto-scroll is holding the live edge. currentAnchorId is the anchored turn being read, and visibleMessageIds are the rows on screen, in order. Visibility costs nothing until something calls its hook.

Streaming Chat

A reply that arrives in chunks changes the transcript while someone is reading it. Most of the work is scroll: when to follow, when to hold still, and when to let the reader decide. A streaming chat should:

1. Move only when the reader asked to. Auto-scroll is never the default.
2. Follow only while they follow. At the live edge the stream stays in view; once they scroll away, it leaves them there.
3. Treat every interaction as a signal. Selecting text, using the keyboard, opening a link or searching should stop the movement too.
4. Start a new turn near the top of the viewport, so it can be read from its first line.
5. Stream the answer into the room below it, instead of pushing everything away.
6. Keep part of the previous turn in view, so the reader knows where they are.
7. Let new content arrive off screen without changing what the reader is looking at.
8. Show what's happening out of view, such as a reply still streaming or new messages below.
9. Keep the latest reply one action away, and follow again from there.
10. Let people jump anywhere: message links, search, unread markers.
11. Reopen a saved thread at the last meaningful turn, often the last user message, not the absolute bottom.
12. Keep the reader's place when layout changes: images load, code blocks render, older messages appear above.
13. Stop, retry, regenerate and errors without moving the conversation.
14. Stay fast in long threads full of markdown, code and images.
15. Stay accessible without the noise: a navigable transcript, focus that stays put, and announcements at a comfortable pace.

Under all of them: never move the reader against their intent. MessageScroller does the scroll part of that list. It does not own your messages, model state, transport, branching or persistence, so the rows stay yours: messages, markers, tools, attachments and the prompt input.

Accessibility

MessageScrollerViewport is a focusable region named Messages (role="region", aria-label="Messages", tabIndex={0}), so a keyboard user can reach the transcript and scroll it. MessageScrollerContent is a log (role="log", aria-relevant="additions"): new rows can be announced, and a reply that grows word by word isn't read out token by token. Pass aria-busy to the content while a turn streams if the announcement should wait for the finished row. The jump button is a real button with a text alternative, Scroll to end or Scroll to start. While there's nothing in its direction it is inert, out of the tab order, and data-active="false", so it never adds an empty focus stop.

Demos

Anchoring

A turn starts at the row that has scrollAnchor. Send with User selected and each question settles near the top, a slice of the previous turn above it, while its reply fills the room below. Switch to Assistant and the replies anchor instead, for a thread where the answer is what people come back to. Anchoring follows the prop, not the role, so a marker or a handoff event can start a turn too. Mark only the rows that start a turn, or every new line pulls the view.

Group Chat

In a group chat the turn often starts with an event, not a message. Add Rocky inserts a join marker with scrollAnchor, so that event is the turn to hold, and Send Message as Rocky adds his message under it. An earlier ping is anchored too. Typing indicators and history rows shouldn't anchor. Reset remounts the thread so you can watch it again.

Previous Context

scrollPreviousItemPeek is how much of the previous turn stays above a new anchor, 64px by default. Drag the slider between 64 and 128, then send: the end of the earlier reply stays in view at that height, so the new question reads as part of the same thread. scrollMargin (24px here) adds room at the top edge on top of the peek. Raise the peek when a question tends to refer to the end of the last answer, like a list or a code block. Too much and the new turn starts halfway down the viewport.

Streaming

autoScroll on the provider follows the reply while the reader is at the live edge. Scroll up mid-reply, by wheel, touch, keys or the scrollbar, and the view stays put while words keep arriving below. The jump button brings you back and starts following again, and so does scrollToEnd. A new turn still anchors near the top first, and following takes over once the reply fills the viewport. The stream here is a timer playing a script, and the AI SDK section below wires a real one.

Opening Position

Three landings for a saved transcript: the first message, the latest line, or the last anchored turn. last-anchor is usually the one to pick, since the reader sees what they asked and where the answer starts instead of the bottom of a long reply. It falls back to end when there is no anchor or the last turn already fits. Set it with defaultScrollPosition on the provider, and the tabs here only replay each choice. Use start to resume from the top, and end when the newest line is what matters.

Load History

Load History puts five earlier messages above the ones on screen, and the row you were reading doesn't move. preserveScrollOnPrepend on the viewport does that, and it's on by default. Give message rows a stable messageId, so the scroller holds that row rather than whatever pixel sits at the edge. Scroll up to find the older rows. Turn the prop off only when loading history should move the reader.

Animation

Pick an entrance and send: the user's message plays it once as it mounts, and the reply streams into a plain row below. The entrances are CSS classes on MessageScrollerItem (animate-in with fade, slide, zoom and blur), so they change transform, opacity and filter but never the row's measured height. Under reduced motion the row just appears, and scrolling behaves the same. Animate the item itself and keep messageId and scrollAnchor on it. Don't animate height, margin or padding, which fights the scroller's positioning.

Commands

The Jump to menu sits in the card's header, outside the scroller, and still drives it. useMessageScroller reads the provider, so a menu, a search result or a permalink handler can call scrollToMessage with a row's messageId. Each question here lands at the top with align: "start" and a smooth scroll. Rows people can jump to need stable ids. The call returns false when the row isn't mounted, so a search can say the message isn't loaded yet.

Visibility

The bars beside the card are the anchored turns, and the one you're reading is drawn in full ink. useMessageScrollerVisibility returns currentAnchorId, the last anchor at or above the reading line, which stays set after it scrolls out of view, and visibleMessageIds, the rows on screen in order. Hover or focus the bars to open the outline, then pick a turn to jump to it. Tracking only runs while something reads the hook, and only rows with a messageId count. Filter visibleMessageIds yourself for a narrower outline, such as search hits.

Scrollable

The transcript opens at the top, and the footer changes as you move: only down at the first message, both ways in the middle, only up at the latest, or a note that every row fits. useMessageScrollerScrollable returns start and end, whether content is hidden above and below, and the footer turns that pair into a sentence. Use the hook for UI beside the scroller. To style the scroller itself, use its data-scrollable attribute instead, which needs no React state.

State

Twelve messages open at the start, with four chips over the list: at the top, at the bottom, older above and newer below. They read the same two booleans as the footer above, and they update without rerendering a row. Use them for a jump button or a status of your own, not a sentence. scrollAnchor on a user row marks a turn, and it is not this state.

Avoiding a Flash on Reload

A scroll container always opens at the top, and HTML can't set scrollTop. A server-rendered transcript would show its oldest messages first, then jump once defaultScrollPosition runs. With end or last-anchor, the viewport has data-pending-scroll until that position is applied, and the styled viewport stays invisible meanwhile, so you see the frame instead of the jump. start needs none of this.

To show end on the first paint, add an inline script right after the viewport: give the viewport an id, scroll it to the bottom and remove the attribute.

const scrollToEndScript = `(function () {
  var viewport = document.getElementById("messages");
  if (!viewport) {
    return;
  }
  viewport.scrollTop = viewport.scrollHeight;
  viewport.removeAttribute("data-pending-scroll");
})()`;

<MessageScroller>
  <MessageScrollerViewport id="messages" suppressHydrationWarning>
    <MessageScrollerContent>{/* transcript */}</MessageScrollerContent>
  </MessageScrollerViewport>
  <script dangerouslySetInnerHTML={{ __html: scrollToEndScript }} />
  <MessageScrollerButton />
</MessageScroller>

Put the script in your page, not in the component. It only works for end, and only when the messages are already in the HTML, so skip it when they load on the client and don't use it with last-anchor. Keep suppressHydrationWarning on the viewport, and pass a nonce if you use a Content Security Policy.

AI SDK

The demos play scripted replies on a timer. With the AI SDK, useChat gives you the same two things, the messages and a status: map the messages to items, anchor the user's, and mark the log busy while a reply streams.

"use client";

import { useChat } from "@ai-sdk/react";
import { DefaultChatTransport } from "ai";

import { Bubble, BubbleContent } from "@/components/ui/bubble";
import { Message, MessageContent } from "@/components/ui/message";
import {
  MessageScroller,
  MessageScrollerButton,
  MessageScrollerContent,
  MessageScrollerItem,
  MessageScrollerProvider,
  MessageScrollerViewport,
} from "@/components/ui/message-scroller";

export function Chat() {
  const { messages, status } = useChat({
    transport: new DefaultChatTransport({ api: "/api/chat" }),
  });

  return (
    <MessageScrollerProvider autoScroll defaultScrollPosition="last-anchor">
      <MessageScroller>
        <MessageScrollerViewport>
          <MessageScrollerContent aria-busy={status === "streaming"}>
            {messages.map((message) => (
              <MessageScrollerItem
                key={message.id}
                messageId={message.id}
                scrollAnchor={message.role === "user"}
              >
                <Message align={message.role === "user" ? "end" : "start"}>
                  <MessageContent>
                    <Bubble variant={message.role === "user" ? "muted" : "ghost"}>
                      <BubbleContent>
                        {message.parts.map((part, index) =>
                          part.type === "text" ? (
                            <span key={`${message.id}-${index}`}>{part.text}</span>
                          ) : null
                        )}
                      </BubbleContent>
                    </Bubble>
                  </MessageContent>
                </Message>
              </MessageScrollerItem>
            ))}
          </MessageScrollerContent>
        </MessageScrollerViewport>
        <MessageScrollerButton />
      </MessageScroller>
    </MessageScrollerProvider>
  );
}

Your prompt input calls sendMessage from the same hook. The user's message is the anchor, so each new question settles near the top while its answer streams below it.

Performance

The scroll hot path stays out of React state. Position, anchoring and follow-output are tracked imperatively and mirrored onto the root and the viewport as data-* attributes, so scrolling and streaming don't rerender the rows, and nothing forces a layout on every scroll. MessageScrollerItem ships with content-visibility: auto and contain-intrinsic-size: rows stay in the DOM for selection, copy, find in page, server rendering and assistive tech, while the browser skips painting the ones far off screen. Visibility tracking only runs while something reads its hook. That covers the range a chat transcript lives in, hundreds to low thousands of turns with markdown and composed rows.

Virtualization

Virtualization stays outside the component. MessageScroller renders real rows and stays fast into the thousands of turns, so most transcripts never need it. When one does, use MessageScrollerViewport as the scroll element and let the virtualizer own the rows.

import { useVirtualizer } from "@tanstack/react-virtual";
import { type ReactNode, useRef } from "react";

export function VirtualizedTranscript({
  messages,
}: {
  messages: { id: string; content: ReactNode }[];
}) {
  const viewportRef = useRef<HTMLDivElement>(null);

  const virtualizer = useVirtualizer({
    count: messages.length,
    estimateSize: () => 86,
    getItemKey: (index) => messages[index]?.id ?? index,
    getScrollElement: () => viewportRef.current,
    overscan: 8,
  });

  return (
    <MessageScrollerProvider>
      <MessageScroller>
        <MessageScrollerViewport ref={viewportRef}>
          <MessageScrollerContent className="block min-h-full">
            <div
              className="relative w-full"
              style={{ height: virtualizer.getTotalSize() }}
            >
              {virtualizer.getVirtualItems().map((virtualItem) => {
                const message = messages[virtualItem.index];

                if (!message) {
                  return null;
                }

                return (
                  <div
                    className="absolute start-0 top-0 w-full"
                    data-index={virtualItem.index}
                    key={virtualItem.key}
                    ref={virtualizer.measureElement}
                    style={{ transform: `translateY(${virtualItem.start}px)` }}
                  >
                    <Message>{message.content}</Message>
                  </div>
                );
              })}
            </div>
          </MessageScrollerContent>
        </MessageScrollerViewport>
        <MessageScrollerButton />
      </MessageScroller>
    </MessageScrollerProvider>
  );
}

FAQ

API Reference