---
title: "Message Scroller"
description: "A bounded conversation viewport that follows streamed replies while preserving the reader’s position."
---

# Message Scroller

A bounded conversation viewport that follows streamed replies while preserving the reader’s position.

## Installation

Install the shared package once in your Exact app. This version is a beta.

```sh
bun add --exact @rightui/ui@0.4.0-beta.4
```

Or choose another package manager:

```sh
npm install --save-exact @rightui/ui@0.4.0-beta.4
pnpm add --save-exact @rightui/ui@0.4.0-beta.4
yarn add --exact @rightui/ui@0.4.0-beta.4
```

Exact compilation uses Bun 1.4.2. Register Geist and Newsreader, declare the font marker and add the root provider using [Installation](/docs/installation).

### Manual source setup

Install an editable copy of the complete package:

```sh
mkdir -p vendor/rightui vendor/rightui-ui
npm pack @rightui/ui@0.4.0-beta.4 --pack-destination vendor/rightui
tar -xzf ./vendor/rightui/rightui-ui-0.4.0-beta.4.tgz -C vendor/rightui-ui --strip-components=1
bun add file:./vendor/rightui-ui
```

Keep package.json, the Contract files, ui.tamber, assets and licenses together.

### Import

```contract
use ContentMessage, MessageScroller, MessageScrollerTranscript, MessageScrollerTranscriptStart, MessageScrollerRichViewport, MessageScrollerViewport, MessageScrollerButton from "@rightui/ui"
```

## Usage

Use MessageScroller for its legacy composer, MessageScrollerTranscript or MessageScrollerTranscriptStart for a virtualized transcript with an external composer, or MessageScrollerRichViewport for caller-owned rich rows. Provide a bounded height and handle send and history in the caller.

## Example

```contract
use FieldFocus from "@rightui/ui"
use FontWeights from "@rightui/ui"
use uiFontFamily, ContentMessage, MessageScrollerViewport, MessageScrollerTranscriptStart, CardFrameOptions, CardHeaderOptions, CardTitle, CardDescription, CardAction, Button, ButtonControl, MessageIcon, InputGroupFrame, InputGroupAddon, Spinner from "@rightui/ui"

fn nextPrompt(step: number): string = step == 0 ? "How do I keep a streamed reply in view?" : step == 1 ? "What if I scroll up to read an earlier reply?" : step == 2 ? "Can I stop the reply without losing my place?" : "How do I load older messages?"
fn replyFor(step: number): string = step == 0 ? "Give the conversation its own bounded viewport. While you are at the bottom, new text stays in view as it arrives.\n\nIn Exact, scrollFollowEnd follows changes to the content size. The composer stays outside the scrolling area, so it never disappears while you read.\n\nTry scrolling upward while this reply is still arriving. The conversation should leave your reading position alone." : step == 1 ? "Scrolling upward means you want to read, so automatic following pauses. New text can continue arriving below without moving the part you are reading.\n\nThe arrow near the bottom lets you return to the latest reply. Once you are back at the end, following resumes.\n\nThis also works when a reply wraps onto another line or grows taller. The scroll container observes its content; it does not need a forced scroll on every character." : step == 2 ? "Yes. Stop keeps the partial response exactly where it is. Resume continues from the same character. Neither action resets the transcript or changes its scroll position.\n\nThe scroll container does not own the model or network transport. Your app supplies the messages, loading state and actions. This example uses a local timed response so you can test the behavior without a server.\n\nReset starts a fresh conversation when you choose to do so." : "Keep a stable ID for every message and prepend the older rows. Exact uses those keys to preserve the visible row when history is inserted above it.\n\nUse the history example below to test this: scroll to the middle, load earlier messages, and check that the message you were reading stays in place.\n\nFor direct navigation, scrollIntoView targets a message ID. It only changes the conversation viewport, not the surrounding documentation page."

component Demo
  props
    width: number
    reduced: bool
  inject
    uiWeights: FontWeights
    uiFont: string
    rightuiDemoTime: number
    rightuiRunDemo: action
  state completed: ContentMessage[] = []
  state question = ""
  state draft = "How do I keep a streamed reply in view?"
  state step = 0
  state activeId = 0
  state started = -1
  state carried = 0
  state more = false
  derive answer = replyFor(step)
  derive count = started < 0 ? carried : min(answer.length, carried + max(0, floor((rightuiDemoTime - started) / 16)))
  derive busy = question != "" and started >= 0 and count < answer.length
  derive paused = question != "" and started < 0 and count < answer.length
  derive thread = question == "" ? completed : completed.concat([ContentMessage(id=activeId, body=question, mine=true), ContentMessage(id=activeId + 1, body=answer.slice(0, count), mine=false)])
  action edit(value: string)
    draft = value
  action send
    if draft.trim() != "" and not busy and not paused
      let nextStep = question == "" ? 0 : min(3, step + 1)
      let nextId = question == "" ? 0 : activeId + 2
      completed = thread
      step = nextStep
      activeId = nextId
      question = draft.trim()
      draft = nextPrompt(min(3, nextStep + 1))
      carried = 0
      started = rightuiDemoTime
      rightuiRunDemo(replyFor(nextStep).length * 16 + 64)
      scrollIntoView("content-scroller", nextId + 1, block="end")
  action stop
    carried = count
    started = -1
  action resume
    started = rightuiDemoTime
    rightuiRunDemo((answer.length - carried) * 16 + 64)
  action reset
    completed = []
    question = ""
    step = 0
    activeId = 0
    carried = 0
    started = -1
    draft = nextPrompt(0)
  action latest
    if question != ""
      if reduced
        scrollIntoView("content-scroller", activeId + 1, block="end", behavior="instant")
      else
        scrollIntoView("content-scroller", activeId + 1, block="end", behavior="smooth")
  action keys(k: string, e: KeyboardEvent)
    if k == "Enter" and not e.shiftKey and not e.isComposing
      preventDefault()
      send()
  action toggleMore
    more = not more
  view
    column width="100%" max-width="24rem" align-self="center" min-width=0 gap="ui.space-16"
      CardFrameOptions(id="scroller-chat", size="default", spacing="0px", imageTop=false, direction="inherit")
        view padding-top="ui.space-24"
          CardHeaderOptions(id="scroller-header", spacing="ui.space-24", divided=true)
            CardTitle(id="scroller-title", title="New chat", level=3)
            CardDescription(id="scroller-description", description="How can I help you today?")
            CardAction(id="scroller-reset-action")
              ButtonControl(id="content-scroller-reset", label="Reset conversation", variant="outline", size="icon-sm", disabled=false, pressed=none, describedBy="", press=reset)
                MessageIcon(name="arrow.clockwise", filled=false)
        if thread.length == 0
          column testId="scroller-empty" height="21rem" box-sizing="border-box" padding="ui.space-24" gap="ui.space-12" align-items="center" justify-content="center" text-align="center"
            view display="flex" align-items="center" justify-content="center" width="ui.space-40" height="ui.space-40" background-color="ui.muted" border-radius="ui.radius-control"
              MessageIcon(name="message", filled=false)
            text "What are we building?" font-size="ui.text-base" font-weight=uiWeights.medium font-family=uiFontFamily(uiFont) data-rightui-font="body"
            text "Press send to start a conversation, then scroll while the reply arrives." font-size="ui.text-sm" line-height="ui.leading-relaxed" color="ui.muted-foreground" font-family=uiFontFamily(uiFont) data-rightui-font="body"
        else
          MessageScrollerViewport(id="content-scroller", messages=thread, height="21rem", busy=busy, reduced=reduced, latest=latest)
        column padding="ui.space-16 ui.space-24 ui.space-24" gap="ui.space-8" min-width=0
          InputGroupFrame(id="scroller-composer")
            textarea class=FieldFocus id="content-scroller-draft" testId="content-scroller-draft" value=draft input=edit key=keys aria-label="Your message" disabled=(busy or paused) rows=2 appearance="none" border="0" resize="none" background-color="transparent" color="ui.foreground" padding="ui.space-12" min-width=0 box-sizing="border-box" font-size="ui.text-sm" line-height="ui.leading-snug" font-family=uiFontFamily(uiFont) data-rightui-font="body"
            InputGroupAddon(id="scroller-composer-actions")
              row width="100%" align-items="center" justify-content="space-between" gap="ui.space-8"
                text (busy ? "Replying…" : paused ? "Reply paused" : "Local demo") testId="scroller-status" role="status" font-size="ui.text-xs" color="ui.muted-foreground" font-family=uiFontFamily(uiFont) data-rightui-font="body"
                if busy
                  ButtonControl(id="content-scroller-stop", label="Stop reply", variant="primary", size="icon-sm", disabled=false, pressed=none, describedBy="", press=stop)
                    svg width="ui.space-14" height="ui.space-14" viewBox="0 0 24 24" fill="currentColor" aria-hidden=true
                      rect x=5 y=5 width=14 height=14 rx=2
                else if paused
                  ButtonControl(id="content-scroller-resume", label="Resume reply", variant="primary", size="icon-sm", disabled=false, pressed=none, describedBy="", press=resume)
                    svg width="ui.space-16" height="ui.space-16" viewBox="0 0 24 24" fill="currentColor" aria-hidden=true
                      path d="m8 5 11 7-11 7z"
                else
                  ButtonControl(id="content-scroller-send", label="Send message", variant="primary", size="icon-sm", disabled=(draft.trim() == ""), pressed=none, describedBy="", press=send)
                    MessageIcon(name="arrow.up", filled=false)
      Button(id="scroller-more", label=(more ? "Hide history example" : "History and message navigation"), variant="ghost", disabled=false, press=toggleMore)
      if more
        HistoryExample(reduced=reduced)

component HistoryExample
  props
    reduced: bool
  state loaded = false
  state messages: ContentMessage[] = [ContentMessage(id=101, body="The component source is ready. Keep each message ID stable when its content changes.", mine=false), ContentMessage(id=102, body="Let's check the small-screen layout and keyboard navigation first.", mine=true), ContentMessage(id=103, body="The viewport is bounded. Only the conversation scrolls; the controls stay outside it.", mine=false), ContentMessage(id=104, body="I am reading the earlier notes. New messages should not pull me away.", mine=true), ContentMessage(id=105, body="Load the previous history while reading this message. Its position should be preserved.", mine=false), ContentMessage(id=106, body="Then use Latest to return to the bottom of the conversation.", mine=true)]
  derive thread = loaded ? [ContentMessage(id=99, body="Earlier: we agreed to use the same public Message and Bubble components throughout the app.", mine=false), ContentMessage(id=100, body="Earlier: the data and network transport remain owned by the app.", mine=true)].concat(messages) : messages
  action history
    loaded = true
  action first
    scrollIntoView("history-scroller", 101, block="start")
  action latest
    scrollIntoView("history-scroller", 106, block="end")
  view
    column gap="ui.space-12" min-width=0
      row gap="ui.space-8" flex-wrap="wrap"
        Button(id="content-scroller-history", label=(loaded ? "History loaded" : "Load earlier"), variant="outline", disabled=loaded, press=history)
        Button(id="controls-first", label="First message", variant="ghost", disabled=false, press=first)
        Button(id="controls-end", label="Latest", variant="ghost", disabled=false, press=latest)
      MessageScrollerTranscriptStart(id="history-scroller", messages=thread, height="18rem", latest=latest)

```

## API Reference

| Property | Type |
| --- | --- |
| MessageScroller.id | string |
| MessageScroller.messages | ContentMessage[] |
| MessageScroller.historyLoaded | bool |
| MessageScroller.loadHistory | action |
| MessageScroller.send | action |
| MessageScroller.latest | action |
| MessageScrollerTranscript.id | string |
| MessageScrollerTranscript.messages | ContentMessage[] |
| MessageScrollerTranscript.height | string |
| MessageScrollerTranscript.latest | action |
| MessageScrollerTranscriptStart.id | string |
| MessageScrollerTranscriptStart.messages | ContentMessage[] |
| MessageScrollerTranscriptStart.height | string |
| MessageScrollerTranscriptStart.latest | action |
| MessageScrollerRichViewport.id | string |
| MessageScrollerRichViewport.height | string |
| MessageScrollerViewport.id | string |
| MessageScrollerViewport.messages | ContentMessage[] |
| MessageScrollerViewport.height | string |
| MessageScrollerViewport.busy | bool |
| MessageScrollerViewport.reduced | bool |
| MessageScrollerViewport.latest | action |
| MessageScrollerButton.id | string |
| MessageScrollerButton.press | action |

## Timed demo setup

The example uses a gated root clock for its local progressive reply. The public viewport needs only your message data and loading state; it does not require a timer or a server.

```contract
  state demoTime = 0
  state demoUntil = 0
  provide
    rightuiDemoTime = demoTime
    rightuiRunDemo = runDemo
  action runDemo(duration: number)
    demoUntil = max(demoUntil, demoTime + duration)
  action tickDemo
    demoTime = min(demoUntil, demoTime + 32)
  task demoClock when demoTime < demoUntil
    every(32, tickDemo)
```

## Source

File: packages/ui/message-scroller.contract

```contract
use FontWeights from "./typography-context.contract"
use uiPopupIn from "./popup-motion.contract"
use uiFontFamily from "./typography-context.contract"
use Button, ButtonControl from "./button.contract"
use MessageFrame, MessageContent, BubbleFrame from "./conversation-parts.contract"
use Message from "./conversation.contract"
use Field from "./styles.contract"

shape ContentMessage
  id: number
  body: string
  mine: bool

component MessageScroller
  props
    id: string
    messages: ContentMessage[]
    historyLoaded: bool
    loadHistory: action
    send: action
    latest: action
  inject
    uiWeights: FontWeights
    uiFont: string
  state draft = ""
  action edit(v: string)
    draft = v
  action post
    if draft.trim() != ""
      send(draft.trim())
      draft = ""
  view
    column id=(id + "-root") testId=id gap="ui.space-12" width="100%" max-width="100%" min-width="0px" box-sizing="border-box"
      row justify-content="center" min-width="0px"
        Button(id=id + "-history", label=(historyLoaded ? "Start of conversation" : "Load earlier messages"), variant="outline", disabled=historyLoaded, press=loadHistory)
      MessageScrollerTranscript(id=id, messages=messages, height="17.5rem", latest=latest)
      row gap="ui.space-8" align-items="center" min-width="0px" max-width="100%"
        input id=(id + "-draft") testId=(id + "-draft") class=Field font-weight=uiWeights.regular value=draft input=edit submit=post placeholder="Your message…" aria-label="Your message" flex="1 1 10rem" min-width="0px" font-family=uiFontFamily(uiFont) data-rightui-font="body"
        Button(id=id + "-send", label="Send", variant="primary", disabled=(draft.trim() == ""), press=post)

component MessageScrollerTranscript
  props
    id: string
    messages: ContentMessage[]
    height: string
    latest: action
  inject
    uiFont: string
  state atLatest = true
  action scrolled(left: number, top: number, e: ScrollEvent)
    atLatest = top + e.clientHeight >= e.scrollHeight - 8
  action joinLatest
    latest()
    atLatest = true
  view
    column gap="ui.space-8" width="100%" max-width="100%" min-width="0px"
      list id=id testId=(id + "-viewport") aria-label="Conversation messages" tabindex=0 appearance="none" virtualized=true scroll-start="end" scrollFollowEnd=true scroll=scrolled height=height min-height="0px" min-width="0px" max-width="100%" box-sizing="border-box" overflow-x="hidden" overscroll-behavior="contain" border-width="ui.border-width" border-style="solid" border-color="ui.border" border-radius="ui.radius-control" background-color="ui.background"
        for message in messages key=message.id
          view id=(id + "-row-" + message.id.toString()) testId=(id + "-row-" + message.id.toString()) padding="ui.space-8 ui.space-12" min-width="0px" max-width="100%" box-sizing="border-box"
            Message(id=id + "-message-" + message.id.toString(), author="", initials=(message.mine ? "YO" : "AI"), time="", align=(message.mine ? "end" : "start"))
              text message.body testId=(id + "-message-" + message.id.toString() + "-body") max-width="90%" min-width="0px" padding="ui.space-8 ui.space-12" border-radius="ui.radius-panel" font-size="ui.text-sm" line-height="ui.leading-code" white-space="pre-wrap" overflow-wrap="anywhere" background-color=(message.mine ? "ui.muted" : "transparent") color="ui.foreground" font-family=uiFontFamily(uiFont) data-rightui-font="body"
      text (atLatest ? "Following latest messages" : "Reading earlier messages; new content stays below") testId=(id + "-follow-state") font-size="ui.text-xs" color="ui.muted-foreground" font-family=uiFontFamily(uiFont) data-rightui-font="body"
      if not atLatest and messages.length > 0
        row justify-content="center"
          Button(id=id + "-latest", label="Jump to latest", variant="outline", disabled=false, press=joinLatest)

component MessageScrollerTranscriptStart
  props
    id: string
    messages: ContentMessage[]
    height: string
    latest: action
  inject
    uiFont: string
  state atLatest = false
  action scrolled(left: number, top: number, e: ScrollEvent)
    atLatest = top + e.clientHeight >= e.scrollHeight - 8
  action joinLatest
    latest()
    atLatest = true
  view
    column gap="ui.space-8" width="100%" max-width="100%" min-width="0px"
      list id=id testId=(id + "-viewport") aria-label="Conversation messages" tabindex=0 appearance="none" virtualized=true scroll-start="start" scrollFollowEnd=true scroll=scrolled height=height min-height="0px" min-width="0px" max-width="100%" box-sizing="border-box" overflow-x="hidden" overscroll-behavior="contain" border-width="ui.border-width" border-style="solid" border-color="ui.border" border-radius="ui.radius-control" background-color="ui.background"
        for message in messages key=message.id
          view id=(id + "-row-" + message.id.toString()) testId=(id + "-row-" + message.id.toString()) padding="ui.space-8 ui.space-12" min-width="0px" max-width="100%" box-sizing="border-box"
            Message(id=id + "-message-" + message.id.toString(), author="", initials=(message.mine ? "YO" : "AI"), time="", align=(message.mine ? "end" : "start"))
              text message.body testId=(id + "-message-" + message.id.toString() + "-body") max-width="90%" min-width="0px" padding="ui.space-8 ui.space-12" border-radius="ui.radius-panel" font-size="ui.text-sm" line-height="ui.leading-code" white-space="pre-wrap" overflow-wrap="anywhere" background-color=(message.mine ? "ui.muted" : "transparent") color="ui.foreground" font-family=uiFontFamily(uiFont) data-rightui-font="body"
      text (atLatest ? "Following latest messages" : "Reading earlier messages; new content stays below") testId=(id + "-follow-state") font-size="ui.text-xs" color="ui.muted-foreground" font-family=uiFontFamily(uiFont) data-rightui-font="body"
      if not atLatest and messages.length > 0
        row justify-content="center"
          Button(id=id + "-latest", label="Jump to latest", variant="outline", disabled=false, press=joinLatest)

// A caller-owned transcript for rich Message, Bubble, Marker, and attachment rows.
// Use a bounded height; this slot is intentionally not virtualized.
component MessageScrollerRichViewport
  props
    id: string
    height: string
  slot
  view
    list id=id testId=(id + "-viewport") aria-label="Conversation messages" tabindex=0 appearance="none" height=height min-height="0px" min-width="0px" max-width="100%" box-sizing="border-box" overflow-x="hidden" overscroll-behavior="contain" border-width="ui.border-width" border-style="solid" border-color="ui.border" border-radius="ui.radius-control" background-color="ui.background"
      children

// The application owns content and transport; the viewport only owns scroll intent.
component MessageScrollerViewport
  props
    id: string
    messages: ContentMessage[]
    height: string
    busy: bool
    reduced: bool
    latest: action
  inject
    uiFont: string
  state atLatest = true
  action scrolled(left: number, top: number, e: ScrollEvent)
    atLatest = top + e.clientHeight >= e.scrollHeight - 8
  action joinLatest
    latest()
    atLatest = true
  view
    column position="relative" height=height min-height=0 min-width=0 max-width="100%" role="log" aria-label="Conversation" aria-live="polite" aria-busy=busy
      list id=id testId=(id + "-viewport") aria-label="Conversation messages" tabindex=0 appearance="none" virtualized=true scroll-start="end" scrollFollowEnd=true scroll=scrolled flex=1 min-height=0 min-width=0 overflow-x="hidden" overscroll-behavior="contain" box-sizing="border-box"
        for message in messages key=message.id
          view id=(id + "-row-" + message.id.toString()) testId=(id + "-row-" + message.id.toString()) padding="ui.space-12 ui.space-24" min-width=0 box-sizing="border-box"
            MessageFrame(id=id + "-message-" + message.id.toString(), align=(message.mine ? "end" : "start"))
              MessageContent(id=id + "-content-" + message.id.toString(), align=(message.mine ? "end" : "start"))
                BubbleFrame(id=id + "-bubble-" + message.id.toString(), align=(message.mine ? "end" : "start"), variant=(message.mine ? "muted" : "ghost"))
                  text (message.body == "" ? "Thinking…" : message.body) testId=(id + "-message-" + message.id.toString() + "-body") white-space="pre-wrap" overflow-wrap="anywhere" font-size="ui.text-sm" line-height="ui.leading-relaxed" font-family=uiFontFamily(uiFont) data-rightui-font="body"
      if not atLatest and messages.length > 0
        view position="absolute" bottom="ui.space-12" left="50%" translate="-50% 0px" animation=(reduced ? "none" : "uiPopupIn ui.duration-fast ui.easing both")
          MessageScrollerButton(id=id + "-latest", press=joinLatest)

component MessageScrollerButton
  props
    id: string
    press: action
  view
    ButtonControl(id=id, label="Jump to latest", variant="outline", size="icon-sm", disabled=false, pressed=none, describedBy="", press=press)
      svg width="ui.space-16" height="ui.space-16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="ui.stroke-standard" stroke-linecap="round" stroke-linejoin="round" aria-hidden=true
        path d="M12 5v14m-7-7 7 7 7-7"

```
