Message Scroller

A chat viewport that starts at the latest message, auto-scrolls while replies stream in, and pauses when the reader scrolls up.

Playground

Can you summarize the launch checklist?

Sure – QA sign-off, changelog entry, and the status page update.

Who owns the status page update?

Ops does. It goes out five minutes before the deploy starts.

Great – anything left after that?

Just the post-launch metrics review on Friday. You're all set.

direction

<MessageScrollerProvider autoScroll defaultScrollPosition="end">
  <MessageScroller>
    <MessageScrollerViewport>
      <MessageScrollerContent>
        {messages.map((message) => (
          <MessageScrollerItem key={message.id} messageId={message.id}>
            <ChatRow message={message} />
          </MessageScrollerItem>
        ))}
      </MessageScrollerContent>
    </MessageScrollerViewport>
    <MessageScrollerButton />
  </MessageScroller>
</MessageScrollerProvider>

Preview

Wrap the tree in MessageScrollerProvider, put the viewport, content and a floating MessageScrollerButton inside MessageScroller, and wrap each row in a MessageScrollerItem. Scroll up – the jump-to-latest button appears.

Can you summarize the launch checklist?

Sure – QA sign-off, changelog entry, and the status page update.

Who owns the status page update?

Ops does. It goes out five minutes before the deploy starts.

Great – anything left after that?

Just the post-launch metrics review on Friday. You're all set.

<MessageScrollerProvider autoScroll defaultScrollPosition="end">
  <MessageScroller>
    <MessageScrollerViewport className="px-4 py-4">
      <MessageScrollerContent>
        {messages.map((message) => (
          <MessageScrollerItem
            key={message.id}
            messageId={message.id}
            scrollAnchor={message.role === "user"}
          >
            <ChatRow message={message} />
          </MessageScrollerItem>
        ))}
      </MessageScrollerContent>
    </MessageScrollerViewport>
    <MessageScrollerButton />
  </MessageScroller>
</MessageScrollerProvider>

Installation

npx shadcn@latest add https://espresso-base-ui.vercel.app/r/message-scroller.json

Usage

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

<MessageScrollerProvider autoScroll defaultScrollPosition="end">
  <MessageScroller>
    <MessageScrollerViewport>
      <MessageScrollerContent>
        <MessageScrollerItem messageId="m1">...</MessageScrollerItem>
        <MessageScrollerItem messageId="m2" scrollAnchor>
          ...
        </MessageScrollerItem>
      </MessageScrollerContent>
    </MessageScrollerViewport>
    <MessageScrollerButton />
  </MessageScroller>
</MessageScrollerProvider>

External controls

Components rendered anywhere inside the provider can drive the viewport with useMessageScroller – scrollToStart, scrollToEnd and scrollToMessage.

Can you summarize the launch checklist?

Sure – QA sign-off, changelog entry, and the status page update.

Who owns the status page update?

Ops does. It goes out five minutes before the deploy starts.

Great – anything left after that?

Just the post-launch metrics review on Friday. You're all set.

function ScrollControls() {
  const { scrollToStart, scrollToEnd } = useMessageScroller()
  return (
    <div className="flex gap-2">
      <Button variant="outline" size="sm" onClick={() => scrollToStart()}>
        <ArrowUpToLineIcon /> Top
      </Button>
      <Button variant="outline" size="sm" onClick={() => scrollToEnd()}>
        <ArrowDownToLineIcon /> Latest
      </Button>
    </div>
  )
}

<MessageScrollerProvider defaultScrollPosition="start">
  <ScrollControls />
  <MessageScroller>...</MessageScroller>
</MessageScrollerProvider>

Anchored turns

Mark the rows that begin a conversation turn – typically the user's messages – with scrollAnchor. When that message is scrolled to, the viewport parks it near the top, with scrollPreviousItemPeek letting a slice of the previous row peek above it for context.

<MessageScrollerProvider
  autoScroll
  defaultScrollPosition="last-anchor"
  scrollPreviousItemPeek={64}
>
  ...
  <MessageScrollerItem messageId={message.id} scrollAnchor={message.role === "user"}>
    <ChatRow message={message} />
  </MessageScrollerItem>
  ...
</MessageScrollerProvider>

API reference

The wrapper re-exports the primitive's hooks: useMessageScroller returns scrollToStart, scrollToEnd and scrollToMessage(messageId, options); useMessageScrollerScrollable reports whether content extends beyond the start or end edge; and useMessageScrollerVisibility exposes currentAnchorId and visibleMessageIds. All hooks must be called under MessageScrollerProvider.