Message Scroller

MessageScroller ships as a headless primitive in the @shadcn/react package. The package owns all of the scroll behavior, anchoring turns, following streamed output, preserving the reader's place as history loads, and tracking visibility, and renders no styles of its own.

The message-scroller.tsx component in the registry is a thin wrapper that adds Tailwind classes on top. Use the package directly when you want full control over the markup and styles, or when you are not using the registry.

For the behavior guide and live examples, see the Message Scroller component.

Installation#

pnpmnpmyarnbun
pnpm add @shadcn/react
Copy

Usage#

Copyimport {
  MessageScroller,
  useMessageScroller,
} from "@shadcn/react/message-scroller"

The package exports a namespace object instead of flat components. The parts and behavior are the same as the styled component, just unstyled.

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

Parts#

If you are coming from the styled component, the flat parts map to the namespace object like this.

The hooks are imported the same way and behave identically, since they read from MessageScroller.Provider.

Copyimport {
  useMessageScroller,
  useMessageScrollerScrollable,
  useMessageScrollerVisibility,
} from "@shadcn/react/message-scroller"

Example#

Here is a complete example that brings its own styles and wires the scroller to the AI SDK.

Copy"use client"
 
import { useChat } from "@ai-sdk/react"
import { MessageScroller } from "@shadcn/react/message-scroller"
import { DefaultChatTransport } from "ai"
 
import { ChatInput } from "@/components/chat-input"
 
export function Chat() {
  const { messages, sendMessage, status } = useChat({
    transport: new DefaultChatTransport({ api: "/api/chat" }),
  })
 
  return (
    <div className="flex h-svh w-full flex-col">
      <MessageScroller.Provider>
        <MessageScroller.Root className="relative flex flex-1 flex-col overflow-hidden">
          <MessageScroller.Viewport className="flex flex-1 flex-col overflow-y-auto">
            <MessageScroller.Content className="flex flex-col gap-4 p-6 text-base">
              {messages.map((message, index) => (
                <MessageScroller.Item
                  key={message.id}
                  messageId={`message-${index}`}
                  scrollAnchor={message.role === "user"}
                >
                  <div className="rounded-lg bg-muted p-4">
                    {message.parts.map((part, i) =>
                      part.type === "text" ? (
                        <span key={i}>{part.text}</span>
                      ) : null
                    )}
                  </div>
                </MessageScroller.Item>
              ))}
            </MessageScroller.Content>
          </MessageScroller.Viewport>
          <MessageScroller.Button className="absolute bottom-2 left-1/2 z-10 -translate-x-1/2 rounded-full border bg-background px-3 py-1 text-sm font-medium inert:opacity-0">
            Jump to latest
          </MessageScroller.Button>
        </MessageScroller.Root>
      </MessageScroller.Provider>
      <ChatInput onSend={sendMessage} disabled={status !== "ready"} />
    </div>
  )
}

Avoiding a Flash on Reload#

A scroll container always opens at the top. HTML has no way to set scrollTop, so a server-rendered transcript shows the oldest messages first. After JavaScript runs, defaultScrollPosition moves the view, and you see a jump.

When defaultScrollPosition is "end" or "last-anchor", the viewport has data-pending-scroll until that position is applied. Give the viewport an id and hide it while the attribute is present. Scope the rule to that id so you do not hide the root.

Copy#messages[data-pending-scroll] {
  visibility: hidden;
}

If you want "end" visible on first paint, add an inline script right after the viewport. Using the same id, scroll it to the bottom and remove data-pending-scroll.

Copyconst scrollToEndScript = `(function () {
  var viewport = document.getElementById("messages")
  if (!viewport) {
    return
  }
  viewport.scrollTop = viewport.scrollHeight
  viewport.removeAttribute("data-pending-scroll")
})()`
 
<MessageScroller.Root>
  <MessageScroller.Viewport id="messages" suppressHydrationWarning>
    <MessageScroller.Content>{/* transcript */}</MessageScroller.Content>
  </MessageScroller.Viewport>
  <script dangerouslySetInnerHTML={{ __html: scrollToEndScript }} />
  <MessageScroller.Button />
</MessageScroller.Root>

Put the script in your page, not in the primitive. It only works for "end", and only when the messages are already in the HTML. Add suppressHydrationWarning on the viewport. If you use a Content Security Policy, pass a nonce.

Do not use this script with "last-anchor". Skip it when messages load on the client.

API Reference#

MessageScroller.Provider#

The headless root. It owns scroll state and the behavior props, and provides them to the parts and the hooks. It renders no DOM of its own.

MessageScroller.Root#

The frame and layout container. It fills its parent, so use it inside a height-constrained layout, within a MessageScroller.Provider.

The root mirrors the scroll-state attributes below (the viewport carries them too), so you can style the container by scroll state, such as edge fades on the frame. Headless usage should hide the viewport while data-pending-scroll is present, using visibility: hidden so layout still exists for the opening scroll.

MessageScroller.Viewport#

The scrollable viewport.

MessageScroller.Content#

The transcript content element. Every direct child should be a MessageScroller.Item.

MessageScroller.Item#

One transcript row: a message, marker, typing row, separator, or load-more row.

MessageScroller.Button#

A button that scrolls to the start or end of the transcript. It is inert and removed from the tab order when there is nothing to scroll toward.

useMessageScroller#

Imperative transcript controls.

All commands return false when the command could not be applied. scrollToStart and scrollToEnd return false only when the viewport is not mounted yet. scrollToMessage returns false when the target is not mounted and cannot be queued.

Command options:

useMessageScrollerScrollable#

Which edges the viewport can scroll toward, for sibling UI that needs the values in JavaScript. Prefer the data-scrollable attribute for styling the scroller itself.

useMessageScrollerVisibility#

Visibility state for outline, search, and active-turn UI. It subscribes separately from useMessageScrollerScrollable, so visibility work is only paid for when a consumer needs it.

Filter visibleMessageIds in your app when you need a narrower outline, such as user messages, anchored turns, or search hits.