Message Scroller

Install

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

Usage

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

<MessageScrollerProvider autoScroll defaultScrollPosition="end">
  <MessageScroller className="h-96">
    <MessageScrollerViewport aria-label="Conversation">
      <MessageScrollerContent>
        {messages.map((m) => (
          <MessageScrollerItem key={m.id} messageId={m.id}>
            {/* 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>;

Give MessageScroller (or its parent) a bounded height so the viewport can overflow and scroll.

Anatomy

• MessageScrollerProvider — holds scroll state: autoScroll, defaultScrollPosition ("start" | "end" | "last-anchor"), scrollPreviousItemPeek, scrollMargin.
• MessageScroller — the root flex column.
• MessageScrollerViewport — the scrollable region. Fades its bottom edge with scroll-fade and hides the scrollbar during programmatic auto-scroll.
• MessageScrollerContent — the inner column; set aria-busy while streaming.
• MessageScrollerItem — one item. content-visibility skips off-screen items; set scrollAnchor on the item that should stay in view and messageId to target it.
• MessageScrollerButton — the floating jump-to-end (or start) button; renders our Button and animates in only when scrolled away. Place it as a direct child of MessageScroller, alongside the viewport (not inside it) so it pins to the frame and floats over the bottom edge.

Hooks

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

Examples

Auto-scrolling thread

Sends pin to the bottom; scroll up and the jump-to-latest button slides in.

Commands

Drive the transcript from outside with useMessageScroller().scrollToMessage(id) — here a "Jump to…" menu.

Scrollable state + scroll-to-start

useMessageScrollerScrollable() reports which edges can scroll. Render a second MessageScrollerButton direction="start" to jump back to the top.

Streaming

Set aria-busy on MessageScrollerContent while a response streams; autoScroll follows the live edge. Pair a shimmer typing bubble for the in-progress cue.

Visibility outline

useMessageScrollerVisibility().currentAnchorId tracks the in-view turn — drive a mini-map / outline that highlights and jumps to the active message.

Restore the anchor on open

Set defaultScrollPosition="last-anchor" on the provider to open at the last item flagged with scrollAnchor instead of the top or bottom — for resuming a thread where the reader left off. scrollPreviousItemPeek leaves a sliver of the message above the anchor visible so the position reads as continuous.

A restyled jump button + live visibility count

MessageScrollerButton forwards variant and size from Button — it defaults to outline, which already is a page-coloured face with the one hairline and the surface-ladder hover — and accepts custom children in place of the default arrow. It docks in and out with the shared motion-dock-in / motion-dock-out pair: 150ms in, 100ms out, translate and fade. useMessageScrollerVisibility() reports every message currently in the viewport via its visibleMessageIds array.

API Reference

MessageScrollerProvider

MessageScrollerProviderProps aliases React.ComponentProps<typeof Primitive.Provider>, a re-exported primitive type the docs type extractor can't introspect — so the rows below are hand-maintained and kept in sync with the primitive.

MessageScrollerItem

MessageScrollerItemProps aliases React.ComponentProps<typeof Primitive.Item>. It accepts all standard <div> props plus the two fields below.

MessageScrollerButton

MessageScroller, MessageScrollerViewport, and MessageScrollerContent accept standard <div> props; the viewport also takes aria-label/aria-labelledby and the content takes aria-busy.

Accessibility

• Give MessageScrollerViewport an aria-label (or aria-labelledby); it is the focusable, scrollable region and uses the global :focus-visible ring.
• The jump button has a visually-hidden label ("Scroll to end" / "Scroll to start") and stays out of the tab order while inactive (pointer-events-none).
• Set aria-busy on MessageScrollerContent while a response streams so assistive tech announces the in-progress state.
• The slide/fade animations honour prefers-reduced-motion via the shared motion tokens.

Do / Don't