Message Scroller

<NaviusMessageScrollerProvider AutoScroll="true" DefaultScrollPosition="end" ScrollPreviousItemPeek="64">
    <NaviusMessageScroller class="relative flex h-full min-h-0 flex-col overflow-hidden">
        <NaviusMessageScrollerViewport class="h-full min-h-0 w-full overflow-y-auto">
            <NaviusMessageScrollerContent class="flex h-max min-h-full flex-col gap-3">
                @foreach (var m in _messages)
                {
                    <NaviusMessageScrollerItem @key="m.Id" MessageId="@m.Id" ScrollAnchor="m.Anchor">
                        @* message row *@
                    </NaviusMessageScrollerItem>
                }
            </NaviusMessageScrollerContent>
        </NaviusMessageScrollerViewport>
        <NaviusMessageScrollerButton class="absolute bottom-3 left-1/2 -translate-x-1/2">
            <ArrowDownIcon />
        </NaviusMessageScrollerButton>
    </NaviusMessageScroller>
</NaviusMessageScrollerProvider>

Features

• Anchors each newly appended turn (ScrollAnchor) near the top of the viewport, keeping a peek of the previous item visible above it (ScrollPreviousItemPeek).
• Follows the live edge while content streams in (AutoScroll), but only while the reader is already there; wheel, touch, keyboard scrolling and explicit jumps release it.
• Preserves the currently visible row when older messages are prepended (PreserveScrollOnPrepend), keyed on stable MessageId values.
• Opens at the end, the start, or the last anchored turn (DefaultScrollPosition).
• A cascaded MessageScrollerContext exposes jump commands (ScrollToMessageAsync, ScrollToStartAsync, ScrollToEndAsync), the scrollable-edge state and a lazy visibility subscription, reachable from anywhere inside the Provider, including outside the scroller frame.
• The scroll hot path runs entirely in the engine: no rerender of transcript rows on scroll or stream.

Installation

Install the brain, or copy just this primitive in with the CLI.

navius add message-scroller

Anatomy

Import the parts and assemble them.

@using Navius.Primitives.Components.MessageScroller

<NaviusMessageScrollerProvider>
    <NaviusMessageScroller>
        <NaviusMessageScrollerViewport>
            <NaviusMessageScrollerContent>
                <NaviusMessageScrollerItem MessageId="m1" ScrollAnchor="true">
                    @* message *@
                </NaviusMessageScrollerItem>
            </NaviusMessageScrollerContent>
        </NaviusMessageScrollerViewport>
        <NaviusMessageScrollerButton />
    </NaviusMessageScroller>
</NaviusMessageScrollerProvider>

API Reference

Provider

Cascades the scroll options and the shared context to every descendant. Renders no DOM of its own.

Root

The scroller frame: the positioning parent for the scroll button and the mirror target for the scrollable-edge and autoscrolling state. Must sit in a height-constrained container. Renders a div.

Data attributes

Viewport

The scroll container: a labelled, keyboard-focusable scroll region (role=region, aria-label=Messages, tabindex=0, all overridable through the attribute seam). Give it a vertical overflow and a bounded size. Renders a div.

Data attributes

Content

The transcript container: a live region (role=log, aria-relevant=additions) so appended rows announce without narrating every streamed token. Every direct child must be an Item. Renders a div.

Data attributes

Item

One transcript row boundary: a message, a marker, a typing indicator, a separator or a load-earlier row. Renders a div.

Data attributes

Button

The scroll-to-start/end control. Context-aware: active only while the viewport can still scroll toward its direction; inert when it can't. Renders a button.

Data attributes

Accessibility

The Viewport is a labelled, keyboard-focusable scroll region (role="region", aria-label="Messages", tabindex="0"). The Content is a live region (role="log", aria-relevant="additions") so appended rows announce without narrating every streamed token; pass aria-busy through the attribute seam while a turn streams if announcements should wait for the completed row. The Button is a real <button> that goes inert with tabindex="-1" when it cannot scroll in its direction, so it never becomes a ghost focus stop.

Keyboard interactions

When the Viewport (or a focusable child) is focused, the standard browser scroll keys apply: Arrow keys, Page Up / Page Down, and Home / End. Navius does not intercept these; the engine only reacts to them to release the streamed-reply follow.