Components

Message scroller

The scrolling transcript of a chat: it opens on the newest message, sticks to the bottom while a reply streams and lets go the moment you scroll up, pins your new message to the top so the reply grows beneath it, holds your place when older messages are added above, and wakes a "jump to latest" button when there is more below. Same parts and hooks as shadcn's message scroller, with the behavior written in, so no extra package.

Install

terminal
npx shadcn@latest add @wobko/message-scroller

First time here? Add the registry to components.json first. How to install

Examples

A transcript that opens at the end

It opens on the newest message. Scroll up and the page fades at the top, the jump button wakes; press it and you glide back down.

Streaming and pinning

Send a message: it is pinned near the top of the view and the reply grows beneath it (autoScroll). When the reply is taller than the room, the view follows its bottom, until you scroll up.

Earlier messages, and jumping to one

Load older messages and the one you were reading stays exactly where it was (preserveScrollOnPrepend). useMessageScroller jumps to a message by id, useMessageScrollerVisibility says which are in view.

A whole chat

Everything at once: a transcript that pins your message and follows the reply, streaming words that soak in, a tool-call note, a code slip with a diff, attachments, a typing pencil, day markers, and the composer with its paper plane and stop button.

Scripted chat

shadcn's `message-scroller-demo`: a whole chat around the scroller. Send plays the next line of a script; your message settles near the top (`scrollAnchor`), the reply streams in below it and the view follows it (`autoScroll`) until you scroll up. The original drives this with the AI SDK; here a few lines of state and a timer stand in for the model.

Scroll status

shadcn's `message-scroller-scrollable`: `useMessageScrollerScrollable` says whether there is more to scroll toward the start and toward the end, so the footer can tell the reader where they can go. The transcript opens at the start (`defaultScrollPosition="start"`).

Transcript outline

shadcn's `message-scroller-visibility`: `useMessageScrollerVisibility` reports the anchor (the last user turn scrolled past the top) and `scrollToMessage` jumps to a turn. The ticks in the header are the outline; open them (click, Enter or Space) for the list. The original opens it on hover beside the card, which a keyboard cannot; a popover can be tabbed into.

Commands

shadcn's `message-scroller-commands`: `useMessageScroller` gives `scrollToMessage`, `scrollToStart` and `scrollToEnd` to anything inside the provider, so a menu in the card header can drive the transcript. Choose a question and it slides to the top of the view.

Opening position

shadcn's `message-scroller-opening-position`: where a saved transcript opens. `start` shows the first message, `end` the newest, and `last-anchor` puts the last message you sent at the top, which is usually where you stopped. The provider is keyed on the choice so it opens afresh each time. (The original uses Tabs with no panels, which axe flags; a toggle group is the right control for a choice with no content behind it.)

Anchoring turns

shadcn's `message-scroller-anchoring`: `scrollAnchor` decides which message settles near the top when it arrives. Pick User or Assistant, send the scripted turns, and watch where each new one lands. Changing the role starts the transcript over.

Keeping context visible

shadcn's `message-scroller-previous-context`: `scrollPreviousItemPeek` is how much of the previous reply stays in sight above a new anchor, and `scrollMargin` the space kept above it. Drag the slider, send the next line, and see how much of the last answer is left above your message.

Group chat

shadcn's `message-scroller-group-chat`: several speakers and an assistant, and a Marker that is itself the anchor. When Rocky joins, the marker (`scrollAnchor` on its MessageScrollerItem) settles near the top and his reply arrives beneath it. Your own lines are on the right, the assistant is unframed, the others are tinted.

API reference

MessageScrollerProvider

Holds the scroll state. Everything else, and the hooks, live inside it. It renders no element.

PropTypeDefaultDescription
autoScrollbooleanfalseFollow the bottom while content grows (a streaming reply), until the person scrolls up; it follows again when they come back to the bottom. It may change while mounted (`autoScroll={status === "streaming"}`): switched on at the bottom it starts following at once, switched off it stops.
defaultScrollPosition"start" | "end" | "last-anchor""end"Where a conversation opens. `last-anchor` puts the last `scrollAnchor` message at the top of the view when the exchange after it is taller than the page.
scrollEdgeThresholdnumber8How close to an edge counts as being at it, px.
scrollPreviousItemPeeknumber64How much of the message before an anchor stays in sight above it, px.
scrollMarginnumber0Space kept above a message scrolled to, px.

MessageScrollerViewport

The scrolling element: `role="region"` labeled "Messages" and focusable, so the keyboard can scroll it. Wheel, touch and scroll keys toward the start are read as the person taking over.

PropTypeDefaultDescription
preserveScrollOnPrependbooleantrueHold the message you are reading still when older messages are added above it.

MessageScrollerContent

The transcript: `role="log"` (polite, additions) with a hidden spacer at the end that makes room for a pinned message on an empty page.

PropTypeDefaultDescription
spacerClassNamestring-Class for the spacer element.

MessageScrollerItem

One message. Give it a `messageId` so it can be scrolled to and reported as visible. Unlike upstream it is not `content-visibility: auto`: that paint containment would cut off the tails and reaction chips that hang past a bubble. For thousands of messages render a window of them, or add `[content-visibility:auto] p-3` yourself.

PropTypeDefaultDescription
messageIdstring-Stable id for `scrollToMessage` and `useMessageScrollerVisibility`.
scrollAnchorbooleanfalseA message that goes to the top of the view when it arrives (your own, so the reply grows below it).

MessageScrollerButton

The jump button: awake (`data-active="true"`) when there is more to scroll in its direction, inert and hidden otherwise. It is a secondary icon Button by default; pass `render` for your own element.

PropTypeDefaultDescription
direction"start" | "end""end"Which way it jumps.
behaviorScrollBehavior"smooth"How it scrolls.
renderReactElement | (props, state) => ReactElement-Render another element, keeping the button's props and state.
variant / sizeButtonProps"secondary" / "icon-sm"For the default Button.

Accessibility

  • The viewport is a labeled `region` and a tab stop, so a keyboard user can scroll with the arrows, Page keys, Home and End; the transcript inside it is a `role="log"`, which announces additions politely.
  • Taking over is detected from wheel, touch and scroll keys going toward the start, and from a dragged scrollbar (a scroll the scroller did not make itself; a press on the container, not on a message, while your message is pinned): following and pinning stop immediately and never fight the reader. Scrolling toward the end while you are already there changes nothing, so a stream keeps being followed.
  • The jump button is `inert` (not focusable, not clickable) while there is nowhere to jump, and has a visually hidden label. Pressing it hands the keyboard to the transcript, so the arrows and Page keys carry on from there instead of restarting at the top of the page.
  • Every word a streaming reply adds is an addition to the `log`, and a screen reader would read the reply piece by piece. While it streams pass `aria-live="off"` to `MessageScrollerContent` and announce the finished reply once from a separate `role="status"` (the examples do); the `TypingIndicator` covers "someone is writing".
  • Smooth scrolling and the button's slide are decoration: with `prefers-reduced-motion` (or a `data-motion="reduced"` ancestor) the durations collapse and the jump button scrolls instantly, even though it asks for `smooth`.
  • The focus ring of the viewport (it is a tab stop) is drawn just inside its edge, because the fade mask would cut a ring drawn outside it.
  • The page fades at an edge only while there is more to scroll there; the fade is a CSS mask, not a color.

Source

The files the CLI copies into your project.

Loading the source