Message Scroller

A transcript scroller for streaming conversations. It follows new messages while the reader is at the bottom, stops when they scroll away, and holds their position when older history loads above.

The scroller fills its parent, so give it a height-constrained container. It needs no card or frame of its own. See Chat for the full-screen layout.

Usage

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
import {
  MessageScroller,
  MessageScrollerButton,
  MessageScrollerContent,
  MessageScrollerItem,
  MessageScrollerProvider,
  MessageScrollerViewport,
} from "@e-infra/design-system"

<div className="h-96">
  <MessageScrollerProvider>
    <MessageScroller>
      <MessageScrollerViewport>
        <MessageScrollerContent>
          {messages.map((message) => (
            <MessageScrollerItem key={message.id} messageId={message.id}>
              <Message align={message.role === "user" ? "end" : "start"}>
                {/* … */}
              </Message>
            </MessageScrollerItem>
          ))}
        </MessageScrollerContent>
      </MessageScrollerViewport>
      <MessageScrollerButton />
    </MessageScroller>
  </MessageScrollerProvider>
</div>

Behaviour

Only reader-driven scrolling switches following off; the component's own scrolling never does. Otherwise a streamed reply would cancel its own autoscroll.

Streaming state

Pass busy to MessageScrollerContent while a reply is streaming. It sets aria-busy, which tells screen readers the log is still being written.

1
2
3
<MessageScrollerContent busy={status === "streaming"}>
  {/* … */}
</MessageScrollerContent>

Entrance animation

Rows that arrive after the first paint fade and rise into place. Rows present on the first render, such as the backlog of a reopened thread, appear immediately, so opening a long transcript does not cascade.

The animation moves only opacity and transform, never layout, so it cannot interfere with autoscroll or position preservation. It is skipped under prefers-reduced-motion.

Use animateOnEnter to override it per row — for example, off on a row you replace in place while streaming.

1
<MessageScrollerItem messageId={message.id} animateOnEnter={false}>

Removing a message

A row cannot animate out after React unmounts it. Mark it exiting, then remove it from your list when onExited fires.

1
2
3
4
5
6
7
8
9
10
const [removing, setRemoving] = useState<string | null>(null)

<MessageScrollerItem
  messageId={message.id}
  exiting={removing === message.id}
  onExited={() => {
    setMessages((current) => current.filter((m) => m.id !== message.id))
    setRemoving(null)
  }}
>

onExited fires exactly once, whether or not the animation runs. A deadline backs it, so a row is never stranded when motion is reduced or the animation event is missed.

The row keeps its height while fading, then collapses when it is removed. Animating the height instead would move every row below it mid-scroll.

Scroll commands

useMessageScroller returns imperative commands. It must be called from inside a MessageScrollerProvider.

1
2
3
4
const { scrollToEnd, scrollToStart, scrollToMessage } = useMessageScroller();

scrollToEnd(); // jump to the latest message
scrollToMessage("msg-42", { align: "center" }); // reveal a specific message

useMessageScrollerScrollable reports which edges are still reachable, for your own scroll affordances.

1
const { start, end } = useMessageScrollerScrollable();

Loading older messages

Prepend to your message array and the reader's position is preserved. preserveScrollOnPrepend is on by default.

1
<MessageScrollerViewport preserveScrollOnPrepend={false}>

Set it to false only when you want prepends to move the viewport.

Components

Props

MessageScrollerProvider

MessageScrollerViewport

MessageScrollerContent

MessageScrollerItem

MessageScrollerButton

Accessibility

The viewport is a focusable role="region" labelled "Messages", so keyboard users can scroll the transcript with arrows, Page Up/Down, and Home/End. The content is a role="log" with aria-relevant="additions", so assistive technology announces new messages rather than re-reading the transcript. The scroll button is inert and aria-hidden when its edge is already reached, keeping it out of the tab order.

Differences from shadcn/ui

This is an e-INFRA implementation rather than a port. The part and prop names match, so the shadcn documentation transfers, but the scroll engine is our own: the upstream behaviour package requires React 19, while this library supports React 18 and 19.

Not implemented: defaultScrollPosition="last-anchor", the scrollAnchor prop and its anchored-streaming mode, and useMessageScrollerVisibility.