# Message Scroller A chat scroll container that anchors turns, opens saved transcripts, follows streamed responses, loads history without jumping, and jumps to any message. ```twig New Chat How can I help you today? I'm building a chat for our app and the scroll behavior is driving me nuts. Every time the AI streams a reply, the whole thread jumps around.

That's the classic streaming scroll problem. Wrap your message list in `MessageScroller` and turn on `autoScroll`: the viewport pins to the bottom as tokens arrive, so users always see the latest text land in place.

The important part: it only auto-scrolls while the reader is already at the bottom. The moment they scroll up to read something earlier, auto-scroll backs off and their position is preserved. You get smooth streaming without fighting the user's intent.

 Okay, but when someone sends a new message the view still feels jarring, like the whole conversation reloads from the top.

`MessageScroller:Item` fixes that with turn anchoring. Set `scrollAnchor` on the turn that should settle near the top instead of blindly snapping to the document bottom.

It also leaves a small peek of the previous exchange visible above the anchor, so context isn't lost. The reply starts in view without that disorienting jump you get from a plain overflow container.

 And if they've scrolled up to re-read an older answer? I don't want to yank them back down.

You won't. Auto-scroll only runs when the viewport is already pinned to the bottom, so scrolling up is a deliberate opt-out: their place in the thread stays put even as new tokens keep arriving below.

When there is content they haven't seen yet, `MessageScroller:Button` appears at the bottom of the viewport. One tap jumps them back to the newest message and re-engages auto-scroll. Same pattern as Slack or iMessage: quiet when you're caught up, helpful when you're not.
Last one: does this work with assistive tech?
``` ## Installation > [!NOTE] > Available since UX Toolkit 3.7. ```shell php bin/console ux:install message-scroller --kit shadcn ``` ## Usage ```twig {% for message in messages %} ... {% endfor %} ``` `MessageScroller` fills its parent, so place it inside a height-constrained container. ```twig
{# transcript #}
``` The scroller does not load or send messages. Add rows to `MessageScroller:Content` the way the page already updates, for instance with a Turbo Stream `append` or `prepend`: the scroller reacts to every row added or removed. Replacing `MessageScroller:Content` as a whole, for instance with a Turbo Stream `replace`, opens the new transcript at its default position. For a transcript of hundreds of rows, let the browser skip the rendering work of the rows far from the viewport: add `[content-visibility:auto] [contain-intrinsic-size:auto_10rem]` to the `class` of `MessageScroller:Item`. The rows stay in the page, for text selection, find in page and assistive technologies. ## Examples ### Anchoring Turns A turn is the part of the conversation that starts a new exchange. In a simple AI chat, that is usually the user's message and the assistant reply that follows. An anchor is the row the viewport treats as the start of that turn. Mark that row with `scrollAnchor`. When a new anchor is appended, the viewport moves it near the top and keeps a peek of the previous row above it, so the new turn does not feel detached from its context. Anchors are not tied to a role: any row can start a turn. ```twig Anchoring Turns The user messages settle near the top edge. Can you show me how anchoring behaves when a new prompt starts the turn? Append the user prompt first, then append the assistant response. With the user prompt as the anchor, the prompt settles near the top and the assistant response fills in below it. What changes when assistant messages are the anchor? Then each assistant response is the item `MessageScroller` keeps in view. This is useful when the reply is the moment you want readers to land on after each turn. Can I switch roles and keep adding turns? Yes. The next appended message with the selected role becomes the anchor, so you can compare user and assistant anchoring in the same transcript. ``` ### Group Chat In a group chat, the turn boundary is often the message that asks the model to respond, or a marker like "Rocky has joined the chat". Typing indicators and history controls usually should not anchor. Because anchoring is not tied to a role, a marker can anchor just like a message. ```twig Group Chat Several participants and an assistant. The marker starts a turn. @mary, the astrophage line keeps matching Venus energy output. Can you check my math? Mary (Agent) Yes. Confirmed. The curve points to a microorganism harvesting stellar energy and breeding near carbon dioxide. If @rocky agrees, this is the clue we need. ping @rocky Rocky has joined the chat Rocky Amaze. Astrophage eats light, makes heat, goes to carbon dioxide. Rocky has fuel model. Grace is smart. ``` ### Keeping Context Visible When a new turn starts, it should still feel like part of the same thread. `scrollPreviousItemPeek` keeps a slice of the previous row visible above the anchor, 64 pixels by default, so the reader keeps their context instead of feeling like the conversation restarted on a blank page. Here it keeps 96 pixels, below a `scrollMargin` of 24 pixels, and the transcript opens on its last turn. ```twig Keeping Context Visible New turns keep part of the previous reply in view. I'm building a chat for our app and the scroll behavior is driving me nuts. Every time the AI streams a reply, the whole thread jumps around.

That's the classic streaming scroll problem. Wrap your message list in `MessageScroller` and turn on `autoScroll`: the viewport pins to the bottom as tokens arrive, so users always see the latest text land in place.

The important part: it only auto-scrolls while the reader is already at the bottom. The moment they scroll up to read something earlier, auto-scroll backs off and their position is preserved. You get smooth streaming without fighting the user's intent.

 Okay, but when someone sends a new message the view still feels jarring, like the whole conversation reloads from the top.

`MessageScroller:Item` fixes that with turn anchoring. Set `scrollAnchor` on the turn that should settle near the top instead of blindly snapping to the document bottom.

It also leaves a small peek of the previous exchange visible above the anchor, so context isn't lost. The reply starts in view without that disorienting jump you get from a plain overflow container.

 And if they've scrolled up to re-read an older answer? I don't want to yank them back down.

You won't. Auto-scroll only runs when the viewport is already pinned to the bottom, so scrolling up is a deliberate opt-out: their place in the thread stays put even as new tokens keep arriving below.

When there is content they haven't seen yet, `MessageScroller:Button` appears at the bottom of the viewport. One tap jumps them back to the newest message and re-engages auto-scroll. Same pattern as Slack or iMessage: quiet when you're caught up, helpful when you're not.

`MessageScroller:Content` sets `role="log"` and `aria-relevant="additions"` by default, so screen readers announce new messages as they stream in.

The scroll button is a real <button> with a visually hidden label, and it's removed from the tab order when you're already at the bottom: no ghost focus stops.

 ``` ### Following the Live Edge When the reader is at the live edge, `autoScroll` keeps a streamed reply in view as it grows. Scrolling away from the live edge releases the view, whether by wheel, touch, keyboard or the scrollbar, and new chunks then arrive without moving the reader. `autoScroll` works with turn anchoring: a new turn settles near the top, and the view only starts following once the reply fills the viewport. Pressing `MessageScroller:Button`, or calling `scrollToEnd`, follows the live edge again. The frame and the viewport have `data-autoscrolling` while that scroll runs. Set `aria-busy` on `MessageScroller:Content` while a reply streams, so screen readers wait for the complete row. ```twig Streaming Messages Auto-scroll follows the live edge of the conversation. I'm building a chat for our app and the scroll behavior is driving me nuts. Every time the AI streams a reply, the whole thread jumps around.

That's the classic streaming scroll problem. Wrap your message list in `MessageScroller` and turn on `autoScroll`: the viewport pins to the bottom as tokens arrive, so users always see the latest text land in place.

The important part: it only auto-scrolls while the reader is already at the bottom. The moment they scroll up to read something earlier, auto-scroll backs off and their position is preserved. You get smooth streaming without fighting the user's intent.

 Okay, but when someone sends a new message the view still feels jarring, like the whole conversation reloads from the top. `MessageScroller:Item` fixes that with turn anchoring. Set `scrollAnchor` on the turn that should settle near the top instead of blindly snapping to the document bottom. ``` ### Opening Saved Threads Reopening a saved thread at the very end often drops the reader into the conversation without enough context. `defaultScrollPosition="last-anchor"` shows the last meaningful turn instead, like the user's latest message, with the reply below it. When there is no anchor, or the last turn already fits in the viewport, it opens at the end. Use `start` to resume at the beginning of a conversation, or `end`, the default, to land on the latest message. A scroll container always opens at the top, so the viewport stays hidden until the controller applies an `end` or `last-anchor` position: you see the frame instead of a jump. ```twig Opening Position Where the transcript starts when you open the thread. {%- for position in ['start', 'end', 'last-anchor'] %} This is the first message the user sent in the conversation. Workspace creation rose 8%, but first invite completion only rose 2%. This is the last message the user sent in the conversation.

Start with the invite step. Teams are creating workspaces but waiting to add collaborators.

Recommended follow-up:

1. Compare invite drop-off by account size. 2. Check whether users who skip invites still return within 24 hours. 3. Review the empty-state copy on the first project screen. 4. Segment activation by template, since template users may not need invites right away.

If that pattern holds, the next experiment should make collaboration useful earlier instead of prompting for invites harder.

 {%- endfor %} start end last-anchor ``` ### Loading Earlier Messages Loading earlier messages should not move the conversation the reader is looking at. When rows are prepended to `MessageScroller:Content`, the viewport keeps the first visible row in place while the history loads above it. Turn it off with `preserveScrollOnPrepend="false"` on `MessageScroller:Viewport`. Give message rows a stable `messageId`: the scroller holds a specific row instead of whatever happens to sit at the viewport edge. ```twig Load History Older messages load above without moving the reader.
Load earlier messages
Can you summarize where the launch checklist stands? Design review is done, the pricing page is in copy review, and the migration guide still needs an owner. Who should own the migration guide? Jordan wrote the previous one and knows the edge cases. If Jordan is busy, Priya has reviewed every migration this quarter. Let's ask Jordan first. What's left after that? Only the announcement email. It depends on the final pricing copy, so it can start as soon as copy review signs off. ``` ### Animating New Messages A `MessageScroller:Item` can be animated directly. A common chat pattern animates the user's message when it is sent, and lets the reply stream into a regular row below it. Animate `transform` and `opacity` only: an entrance that animates the height, the margin or the padding fights the positioning of the scroller. Skip the animation when the reader prefers reduced motion. ```twig Animation User messages rise from the live edge as they are sent. I'm building a chat for our app and the scroll behavior is driving me nuts. Every time the AI streams a reply, the whole thread jumps around.

That's the classic streaming scroll problem. Wrap your message list in `MessageScroller` and turn on `autoScroll`: the viewport pins to the bottom as tokens arrive, so users always see the latest text land in place.

The important part: it only auto-scrolls while the reader is already at the bottom. The moment they scroll up to read something earlier, auto-scroll backs off and their position is preserved. You get smooth streaming without fighting the user's intent.

 Okay, but when someone sends a new message the view still feels jarring, like the whole conversation reloads from the top.

`MessageScroller:Item` fixes that with turn anchoring. Set `scrollAnchor` on the turn that should settle near the top instead of blindly snapping to the document bottom.

It also leaves a small peek of the previous exchange visible above the anchor, so context isn't lost. The reply starts in view without that disorienting jump you get from a plain overflow container.

 ``` ### Jumping to Messages Search results, permalinks, outlines and toolbar buttons often drive the transcript from outside the list. The `message-scroller` controller has three actions for them: `scrollToMessage`, `scrollToStart` and `scrollToEnd`. They work from any element inside `MessageScroller:Provider`, including controls outside the `MessageScroller` frame. `scrollToMessage` takes the `messageId` of the row in its `id` param, and optional `align` (`start`, `center`, `end` or `nearest`) and `behavior` (`auto` or `smooth`) params. When no row is rendered yet, the jump waits for the transcript to arrive. ```twig Commands Drive the transcript from outside. Jump to... Conversations We're seeing activation dip after works... What should I compare before we change ... Can you turn that into an experiment? What's the risk if we delay the invite ... We're seeing activation dip after workspace creation. Can you help me find the likely step?

The sharpest drop is between creating the workspace and inviting the first teammate.

Workspace creation is still healthy, but the invite step is where users pause. That suggests the product is asking for collaboration before the user has enough confidence in the workspace.

 What should I compare before we change the onboarding flow?

Compare three cohorts:

1. Users who choose a template before inviting teammates. 2. Users who start from a blank workspace. 3. Users who skip invites and return within 24 hours.

If template users invite faster, the fix is probably better first-run guidance rather than a louder invite prompt.

 Can you turn that into an experiment?

Yes. Create a variant that shows a short checklist after workspace creation:

- Pick a template. - Add one project detail. - Invite a teammate when the workspace has context.

Measure first invite completion, 24-hour return rate, and whether teams create a second project.

 What's the risk if we delay the invite prompt?

The main risk is reducing team creation for accounts that already know who they want to invite.

To protect that path, keep the invite action visible in the header and only change the primary empty-state guidance. That gives confident teams a direct route without forcing uncertain users through the invite step too early.

 ``` ### Tracking the Reader's Position An outline or a jump menu often highlights the turn the reader is in. Mark its controls as `anchorLink` targets of the controller: the one whose `id` param is the current turn gets `aria-current="location"`, the others `aria-current="false"`. The current turn is the last anchor to reach the line where anchored turns settle, and it stays current after its top scrolls out of view. The tracking only runs while the provider holds an `anchorLink` target. ```twig
Transcript Outline Track the current anchored turn. We're seeing activation dip after workspace creation. Can you help me find the likely step?

The sharpest drop is between creating the workspace and inviting the first teammate.

Workspace creation is still healthy, but the invite step is where users pause. That suggests the product is asking for collaboration before the user has enough confidence in the workspace.

 What should I compare before we change the onboarding flow?

Compare three cohorts:

1. Users who choose a template before inviting teammates. 2. Users who start from a blank workspace. 3. Users who skip invites and return within 24 hours.

If template users invite faster, the fix is probably better first-run guidance rather than a louder invite prompt.

 Can you turn that into an experiment?

Yes. Create a variant that shows a short checklist after workspace creation:

- Pick a template. - Add one project detail. - Invite a teammate when the workspace has context.

Measure first invite completion, 24-hour return rate, and whether teams create a second project.

 What's the risk if we delay the invite prompt?

The main risk is reducing team creation for accounts that already know who they want to invite.

To protect that path, keep the invite action visible in the header and only change the primary empty-state guidance. That gives confident teams a direct route without forcing uncertain users through the invite step too early.
``` ### Reading Scroll State The provider, the frame and the viewport have a `data-scrollable` attribute listing the edges the viewport can still scroll toward: `start`, `end`, or both. It is absent when everything fits. Style anything inside the provider from it, with the `group/message-scroller-provider` group, or the frame with `group/message-scroller`. ```twig Scroll Status Where the reader can scroll to from the current position. {%- for checkpoint in [1, 3, 5, 7, 9, 11] %} Review scroll checkpoint {{ checkpoint }}.

Checkpoint {{ checkpoint + 1 }} is synced. The scroll state updates as the viewport moves.

When the reader is at the first message, the footer should only point them down. Once they move into the middle of the transcript, it should explain that both directions are available.

At the latest message, the footer should switch again and only point them back up.

 {%- endfor %}

All messages fit in the viewport.

 ``` ### RTL To enable RTL support, set the `dir="rtl"` attribute on the root element. ```twig
{# Arabic #}
محادثة جديدة كيف يمكنني مساعدتك اليوم؟ لماذا يقفز المحادثة كلما وصل رد جديد؟ لأن الحاوية تنتقل إلى الأسفل مع كل جزء جديد. يثبّت MessageScroller الدور الجديد قرب الأعلى، ولا يتابع الرد إلا إذا كان القارئ في النهاية. وإذا صعدتُ لقراءة رسالة قديمة؟ يبقى مكانك كما هو. يظهر زر في أسفل العرض للعودة إلى آخر رسالة عندما تريد.
{# Hebrew #}
שיחה חדשה איך אפשר לעזור היום? למה השיחה קופצת בכל פעם שמגיעה תשובה חדשה? כי המכל גולל למטה עם כל חלק חדש. MessageScroller מצמיד את התור החדש קרוב לראש, ועוקב אחרי התשובה רק כשהקורא נמצא בסוף. ואם גללתי למעלה כדי לקרוא הודעה ישנה? המקום שלך נשמר. כפתור מופיע בתחתית התצוגה כדי לחזור להודעה האחרונה מתי שתרצה.
``` ## Accessibility - `MessageScroller:Viewport` is a labelled region the keyboard can reach: it renders `role="region"`, `aria-label="Messages"` and `tabindex="0"`, so keyboard users can focus the transcript and scroll it. Pass another `aria-label` to name it after the conversation. - `MessageScroller:Content` is a live region, with `role="log"` and `aria-relevant="additions"`: new rows are announced, but streamed text is not read out chunk by chunk. Set `aria-busy="true"` while a reply streams, so the announcement waits for the complete row. - `MessageScroller:Button` renders a real `