Message Scroller

InstallCopy Anchor Link

pnpm exec vegastack-design verify message-scroller

pnpm dlx shadcn@4.21.0 add @vegastack/message-scroller

UsageCopy Anchor Link

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

<MessageScrollerProvider autoScroll defaultScrollPosition="end">
  <MessageScroller>
    <MessageScrollerViewport aria-label="Conversation">
      <MessageScrollerContent>
        {messages.map((message) => (
          <MessageScrollerItem
            key={message.id}
            messageId={message.id}
            scrollAnchor={message.role === "user"}
          >
            {/* a Message row */}
          </MessageScrollerItem>
        ))}
      </MessageScrollerContent>
    </MessageScrollerViewport>
    {/* The button is a SIBLING of the viewport — a direct child of the
        relative MessageScroller frame — so it floats over the bottom edge. */}
    <MessageScrollerButton direction="end" />
  </MessageScroller>
</MessageScrollerProvider>;

MessageScroller fills its parent, so give it (or that parent) a bounded height and let the viewport do the overflowing.

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

AnatomyCopy Anchor Link

• MessageScrollerProvider — the headless root. Owns scroll state and the behaviour props: autoScroll, defaultScrollPosition, scrollPreviousItemPeek, scrollMargin, scrollEdgeThreshold.
• MessageScroller — the styled frame. A relative, clipping flex column.
• MessageScrollerViewport — the scrollable element. Receives native scroll events, preserves the visible row when older messages are prepended, and fades its bottom edge with scroll-fade.
• MessageScrollerContent — the transcript container, and the live region for new rows.
• MessageScrollerItem — one row boundary. Wrap every direct child of the content so the scroller can measure, anchor, preserve position and jump to it. A row can be a message, a marker, a typing indicator or a "load earlier" control.
• MessageScrollerButton — the scroll control. Renders our Button and is inert until there is content in its direction.

HooksCopy Anchor Link

• useMessageScroller() → scrollToEnd(), scrollToStart(), scrollToMessage(id, options).
• useMessageScrollerScrollable() → { start, end } — whether each edge can scroll.
• useMessageScrollerVisibility() → { currentAnchorId, visibleMessageIds }.

ExamplesCopy Anchor Link

What Makes a Great Streaming Chat ExperienceCopy Anchor Link

Streaming broke the old model. Messages arrive in chunks while the reader may still be reading, scrolling, or looking somewhere else, so the whole problem becomes scroll: when to follow, when to hold, and when to let the reader decide.

Move only when the reader asked to move; follow only while they are following; treat every interaction — scroll, selection, a keystroke, a link — as a signal to stop moving; start a new turn near the top so it can be read from the beginning; keep enough of the previous turn visible that the exchange stays connected; let the rest arrive offscreen; and make coming back to the live edge one obvious action. Never move the reader against their intent.

MessageScrollerCopy Anchor Link

MessageScrollerProvider owns the scroll state and the transcript-row behaviour — opening position, streamed output, new-turn anchoring, prepended history, visibility and the scroll commands. MessageScroller is the styled frame that renders inside it.

It is scoped to the scroll viewport, and to nothing else: it does not own messages, AI state, transport, persistence, branching or model state. Your product code stays focused on composing messages, markers, tools, attachments and prompt inputs.

CompositionCopy Anchor Link

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

The button is a sibling of the viewport, not a child of it: it pins to the frame and floats over the edge it scrolls toward.

Core ConceptsCopy Anchor Link

A turn is the part of the conversation that starts a new exchange — usually the user's message and the reply that follows it. An anchor is the row the viewport should treat as the start of that turn; mark it with scrollAnchor.

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

Anchors are not tied to a message role. Any row can be one — a user message, a system marker, a handoff event — and 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 never feels detached from its context.

Group ChatCopy Anchor Link

In a group chat the turn boundary is more specific than "the user message" — it is the message that asks for a response, or a marker like "Marcus joined the chat". Because anchoring is role-independent, a marker anchors exactly as easily as a message, and a typing indicator or a history control simply does not.

<MessageScrollerItem messageId="marcus-joined" scrollAnchor>
  <Marker variant="separator">
    <MarkerContent>Marcus joined the chat</MarkerContent>
  </Marker>
</MessageScrollerItem>

Keeping Context VisibleCopy Anchor Link

scrollPreviousItemPeek keeps a slice of the previous item visible above the anchor, so a new turn still reads as part of the same continuous thread instead of restarting on a blank page.

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

Following the Live EdgeCopy Anchor Link

With autoScroll, the viewport follows new content — but only while the reader is at the live edge. Set aria-busy on the content while a turn streams so announcements wait for the completed row.

<MessageScrollerContent aria-busy={status === "streaming"}>
  {/* messages */}
</MessageScrollerContent>

Opening Saved ThreadsCopy Anchor Link

A saved conversation should open at the last meaningful turn, which is usually the last user message rather than the absolute bottom. defaultScrollPosition="last-anchor" restores the last row flagged with scrollAnchor.

Avoiding a Flash on ReloadCopy Anchor Link

A scroll container always opens at the top and HTML has no way to set scrollTop, so a server-rendered transcript would show the oldest messages and then jump once JavaScript applies defaultScrollPosition. While "end" or "last-anchor" is still pending, the viewport carries data-pending-scroll and the styled recipe keeps it invisible: you see the frame, never the jump. "start" needs none of this.

If you want "end" visible on first paint, give the viewport an id and scroll it from an inline script placed right after it in your page — never inside the scroller — with suppressHydrationWarning on the viewport and a nonce if you run a Content Security Policy. It only works for "end", and only when the messages are already in the HTML.

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>;

Loading Earlier MessagesCopy Anchor Link

Prepending older rows must not move the conversation the reader is already looking at. The viewport preserves the visible row while history loads above it — preserveScrollOnPrepend, on by default.

Animating New MessagesCopy Anchor Link

MessageScrollerItem animates directly: keep messageId and scrollAnchor on it and use transform and opacity for the entrance. Here the sent row wears motion-enter-up, the system's fade-and-rise arrival, so it looks like it comes from the live edge; base.css collapses it under prefers-reduced-motion.

Jumping to MessagesCopy Anchor Link

useMessageScroller().scrollToMessage(id, options) drives the transcript from outside — a jump menu, a search result, an unread marker, a permalink.

Tracking the Reader's PositionCopy Anchor Link

useMessageScrollerVisibility() reports currentAnchorId and visibleMessageIds. It is pay-for-what-you-use: nothing is tracked until something subscribes.

Reading Scroll StateCopy Anchor Link

useMessageScrollerScrollable() reports which edges can still scroll, which is what a second MessageScrollerButton direction="start" — or your own affordance — reads.

PerformanceCopy Anchor Link

The goal is to keep the scroll hot path outside React state: no rerenders for transcript rows, no forced layout on every scroll, and as little off-screen paint as the browser can avoid. Scroll position, anchoring and follow-output are tracked imperatively and mirrored onto the root and viewport as data-* attributes.

MessageScrollerItem ships with content-visibility: auto and contain-intrinsic-size, so rows stay in the DOM for selection, copy, find-in-page, SSR and assistive tech while the browser skips rendering work for rows far outside the viewport. That is comfortable for the expected range of a chat transcript: hundreds to low thousands of turns, markdown and composed rows included.

VirtualizationCopy Anchor Link

Virtualisation is deliberately outside the primitive — real DOM rows stay fast well into the thousands of turns, so most transcripts never need it. When one does, use MessageScrollerViewport as the virtualiser's scroll element and let the virtualiser own the rows.

UnstyledCopy Anchor Link

The behaviour comes from @shadcn/react/message-scroller. Mount those parts directly when the transcript has to look like something else entirely; the styled components above are that engine plus our token chrome and nothing more.

Jump Button VariantsCopy Anchor Link

MessageScrollerButton forwards variant and size to Button and accepts custom children in place of the default arrow. It defaults to secondary / icon-sm.

API ReferenceCopy Anchor Link

MessageScrollerProviderCopy Anchor Link

The provider is a pass-through to the @shadcn/react primitive, whose props the docs type extractor cannot introspect — so the rows below are hand-maintained against the engine.

MessageScrollerViewportCopy Anchor Link

MessageScrollerItemCopy Anchor Link

MessageScrollerButtonCopy Anchor Link

MessageScroller and MessageScrollerContent add no props of their own — each accepts everything the underlying <div> accepts, and the content additionally takes aria-busy and aria-relevant.

AccessibilityCopy Anchor Link

• MessageScrollerViewport is a labelled, keyboard-focusable scroll region: the engine gives it role="region", aria-label="Messages" and tabIndex={0}, so a keyboard user can focus the transcript and scroll it directly. Pass your own aria-label when the page has more than one.
• MessageScrollerContent is the live region — role="log" with aria-relevant="additions" — so new rows can be announced without every streamed token being read out. Set aria-busy while a turn streams and the announcement waits for the completed row (A11Y-3). The component adds no second live region of its own (A11Y-4): one log is the whole announcement surface.
• MessageScrollerButton is a real button with a visually hidden label ("Scroll to end" / "Scroll to start"). With nothing to scroll toward it sets inert, tabIndex={-1} and data-active="false", so an inactive control is never an extra focus stop.
• Focus on the viewport is the global 2px :focus-visible outline, pulled inside the frame's clip with focus-visible:-outline-offset-2 (FOC-9) so it is not cut away by overflow-hidden.
• The jump control's click scroll is forced to behavior: "auto" under prefers-reduced-motion (MOT-5), and the dock-in/dock-out transition collapses with the global reduced-motion reset.

Do / Don'tCopy Anchor Link

DeviationsCopy Anchor Link

Upstream's file plus packages/ui/upstream/patches/message-scroller.patch. Every hunk:

• FOC-9 — MessageScrollerViewport gains focus-visible:-outline-offset-2. The viewport is a tab stop and MessageScroller above it clips with overflow-hidden, so base.css's outward outline-offset: 1px is drawn and then cut away by the ancestor. This is the one permitted local focus deviation; nothing but the offset moves.
• MOT-5 — MessageScrollerButton reads usePrefersReducedMotion() and forces the engine's scroll behavior to "auto". The engine defaults it to "smooth" and knows nothing about the preference, and the global reset in base.css cannot reach it: a scrollTo that asks for smooth explicitly outranks the scroll-behavior property. This wrapper is the only place the preference can be honoured, so it overrides whatever the consumer passed.
• A11Y-3, A11Y-4 — NO HUNK. Measured in @shadcn/react@0.3.1: Content already renders role="log" with aria-relevant="additions", and Viewport renders role="region" with aria-label="Messages". That is A11Y-3 verbatim — a polite region announcing added rows rather than every streamed token, and no alert anywhere — and A11Y-4's one-region rule is satisfied by that single log; a useAnnouncer beside it would announce every message twice. message-scroller.test.tsx asserts both roles and the aria-relevant value, so the day the engine drops them the claim fails instead of going quiet.
• A11Y-2 — audited, NO HUNK. The one control is MessageScrollerButton, a Button at size="icon-sm" — size-7, 28px, over the floor.
• NOT PATCHED, FLAGGED FOR MK — the engine writes tabIndex: value ?? 0 on the viewport unconditionally, so a transcript short enough not to scroll is still a tab stop, which is the half of A11Y-6 that Base UI's ScrollArea.Viewport gets right. A11Y-6 is not assigned to this component, its second clause licenses a named role="region" viewport, and the pre-reset component did not condition it either, so nothing is invented here. The test pins the engine's exact shape, so this note fails as stale the day upstream conditions it.
• DOC-1, DOC-2 — cn is imported from @vegastack/design, and the rest of the diff is prettier's reflow plus the registry-stamp.mjs provenance header the three-copy model needs.