`maintainVisibleContentPosition` does not hold scroll position when prepending items while scrolled near the bottom

[ACHP]

Summary

When prepending items to the start of the list, maintainVisibleContentPosition keeps the visible content stable only when scrolled near the top. If the list is scrolled near the bottom (e.g. a chat opened at the last message, then loading older history), prepending older items shifts the visible content instead of anchoring it.

Expected behavior

After items are prepended at the start of the data, the row that is currently visible should stay visually fixed regardless of the current scroll position.

Actual behavior

• Scrolled near the top → works as expected, visible content is maintained. (video 1)
• Scrolled near the bottom → visible content is NOT maintained, the list jumps. (video 2)

Videos

When scrolled to bottom, mvcp does not works

llbug.mp4

When scrolled to top, mvcp does works

llnobug.mp4

Captured item heights and list geometry come from a real conversation that exhibits the jump. The list opens at the last item of an initial "page", then older items are prepended (mirroring loading older messages).

Steps

1. Tap Remount the list opens at the last item of the initial 13-item page (scrolled near the bottom).
2. Tap Load older the 7 older items are prepended to the start of the data.
3. Observe: the visible row jumps instead of staying anchored.
4. Compare with the same action performed while scrolled near the top — there it stays anchored.

Configuration notes

• maintainVisibleContentPosition enabled.
• initialScrollIndex={{ index, viewPosition: 0 }} to open at the end of the initial page.
• recycleItems enabled.
• No estimatedItemSize — heights are measured.
• Variable item heights, including a few large rows (~425px) that amplify the visible jump.

I did a repro here

https://github.com/ACHP/legend-list/tree/mvcp-bug

But you can also just copy paste from here:

See the code directly

```typescript import { useMemo, useRef, useState } from "react";

import { LegendList, type LegendListRef } from "@legendapp/list/react";

/**

• Reproducible sandbox for the LegendList open-scroll jump on prepend.
• The item heights and the list rect below were captured from a real app
• (a conversation that exhibits a scroll jump when older messages load). The
• list is positioned at the exact same screen geometry so the configuration
• matches.
• Repro:
• 1. Tap "Remount" — list opens at the last item of the initial page.
• 2. Tap "Load older" — the older items are prepended.
• Expected: with maintainVisibleContentPosition, the currently visible row
• should stay put when older items are prepended.
• Bug: the scroll position is NOT maintained on that prepend.
  */
  const ITEM_HEIGHTS = [
  { height: 48.09027862548828, index: 0, width: 818.3333740234375 },
  { height: 45.659725189208984, index: 1, width: 818.3333740234375 },
  { height: 37.65625, index: 2, width: 818.3333740234375 },
  { height: 37.65625, index: 3, width: 818.3333740234375 },
  { height: 37.65625, index: 4, width: 818.3333740234375 },
  { height: 37.65625, index: 5, width: 818.3333740234375 },
  { height: 37.65625, index: 6, width: 818.3333740234375 },
  { height: 37.65625, index: 7, width: 818.3333740234375 },
  { height: 37.65625, index: 8, width: 818.3333740234375 },
  { height: 37.65625, index: 9, width: 818.3333740234375 },
  { height: 37.65625, index: 10, width: 818.3333740234375 },
  { height: 37.65625, index: 11, width: 818.3333740234375 },
  { height: 425.9895935058594, index: 12, width: 818.3333740234375 },
  { height: 68.54167175292969, index: 13, width: 818.3333740234375 },
  { height: 37.65625, index: 14, width: 818.3333740234375 },
  { height: 48.09027862548828, index: 15, width: 818.3333740234375 },
  { height: 434.8871765136719, index: 16, width: 818.3333740234375 },
  { height: 48.09027862548828, index: 17, width: 818.3333740234375 },
  { height: 68.54167175292969, index: 18, width: 818.3333740234375 },
  { height: 37.65625, index: 19, width: 818.3333740234375 },
  ].map((it) => it.height);

const LIST_RECT = {
height: 817.9166870117188,
width: 1218.3333740234375,
x: 460.5555725097656,
y: 49.548614501953125,
};

interface Item {
id: string;
index: number;
height: number;
}

const DATA: Array = ITEM_HEIGHTS.map((height, index) => ({
height,
id: item-${index},
index,
}));

// We first show only the last N items (the "last page"), then prepend the
// older ones — mirroring how the app opens at the end and then loads older
// messages. The bug appears on that prepend (MVCP re-anchoring).
const INITIAL_COUNT = 13;
const INITIAL_LAST_INDEX = INITIAL_COUNT - 1;

export default function PrependMvcpJumpExample() {
const listRef = useRef(null);
// Remounting re-triggers the initial open; showAll prepends the older items.
const [mountKey, setMountKey] = useState(0);
const [showAll, setShowAll] = useState(false);

// Mirror the app workaround: items get fresh refs so LegendList re-renders.
// https://github.com/LegendApp/legend-list/issues/455
const visibleData = useMemo(() => {
    const slice = showAll ? DATA : DATA.slice(-INITIAL_COUNT);
    return slice.map((item) => ({ ...item }));
}, [showAll, mountKey]);

const remount = () => {
    setShowAll(false);
    setMountKey((key) => key + 1);
};

return (
    <div style={{ background: "#ddd", flex: 1, minHeight: 0, position: "relative" }}>
        <div style={{ display: "flex", flexDirection: "column", gap: 8, left: 12, position: "absolute", top: 12, zIndex: 10 }}>
            <button onClick={remount} style={{ background: "#333", borderRadius: 6, color: "white", padding: 10 }} type="button">
                Remount ({INITIAL_COUNT} last only)
            </button>
            <button
                onClick={() => setShowAll(true)}
                style={{ background: "#1a73e8", borderRadius: 6, color: "white", padding: 10 }}
                type="button"
            >
                Load older (prepend {DATA.length - INITIAL_COUNT})
            </button>
        </div>

        <div
            style={{
                background: "white",
                border: "1px solid red",
                boxSizing: "border-box",
                display: "flex",
                flexDirection: "column",
                height: LIST_RECT.height,
                left: LIST_RECT.x,
                position: "absolute",
                top: LIST_RECT.y,
                width: LIST_RECT.width,
            }}
        >
            <LegendList<Item>
                className="min-h-0 flex-1"
                data={visibleData}
                initialScrollIndex={{ index: INITIAL_LAST_INDEX, viewPosition: 0 }}
                itemsAreEqual={(itA, itB) => itA.id === itB.id}
                key={mountKey}
                keyExtractor={(item) => item.id}
                maintainScrollAtEndThreshold={1}
                maintainVisibleContentPosition
                recycleItems
                ref={listRef}
                renderItem={({ item }) => (
                    <div
                        style={{
                            alignItems: "center",
                            background: item.height > 200 ? "#e8f0fe" : "#fff",
                            borderBottom: "1px solid #ccc",
                            boxSizing: "border-box",
                            display: "flex",
                            height: item.height,
                            paddingLeft: 12,
                            paddingRight: 12,
                        }}
                    >
                        <span>{`#${item.index} · ${Math.round(item.height)}px`}</span>
                    </div>
                )}
            />
        </div>
    </div>
);

}

</p>
</details> 

[ACHP]

Update

I used Claude to try to find the bug and try some patches and it finally found something

I'm not sure you care about that, but the way I worked with claude is that I told him to make hypothesis, and log things, then I copy pasted log from the console and feed it back to claude, so it can validate its hypothesis.
So it didn't just wild guessed by reading the code, so I'm quite confident about what he found but ... I can't be sure.

Claude's explanation:

MVCP runs in two passes:

1. Prepend pass. The newly prepended items are off-screen (above the viewport), so they're
   unmeasured. MVCP sizes them from the running average item size. In a list with mixed
   heights (e.g. a couple of tall image rows), that average is much larger than the small text
   rows being prepended — so MVCP computes an over-sized correction and scrolls down too far.
   At this instant the view still looks stable because the content above grew by the same
   (wrong) amount.
2. Settle pass. The browser measures the prepended items at their real (smaller) size, the
   content above shrinks, and MVCP issues a correcting scroll.

The bug is in how that correction is applied. On web the adjustment is applied as a
relative el.scrollBy(delta), while the list tracks scroll as an absolute state.scroll.
Between the two passes the content shrinks below the over-shot scroll position, so the
browser silently clamps the DOM scrollTop — desyncing it from state.scroll. The settle pass
then applies its relative delta from the already-clamped position, moving too far.
state.scroll ends up correct; the actual DOM scroll ends up off by roughly the clamp
amount, leaving the list scrolled to the wrong place.

Near the top the over-shoot never reaches the content end, so the browser never clamps, DOM
and state.scroll stay in sync, and the relative delta is exact — which is why the top
works and the bottom doesn't. (drawDistance has no effect, since this is a scroll-clamp
issue, not a render-window one.)

Proof (logs from a minimal repro), bottom case:

• Pass 1: over-shoot → state.scroll and DOM both reach 1278 (temporary padding lets the DOM
  get there).
• Content then shrinks → real max scroll becomes ~829 → browser clamps DOM 1278 → 829, but
  state.scroll stays 1278.
• Pass 2: computes correct target state.scroll = 829, but applies relative scrollBy(-448)
  from the clamped DOM 829 → 381 — ~448px too high. Wrong final position.

Top case under the same steps lands exactly right because no clamp ever occurs.

Fix (works in my testing): in the web ScrollAdjust apply path, reconcile against the live
DOM scroll instead of applying the signal delta blindly — move the DOM to the intended
absolute position (state.scroll + any user anchor offset), computing the delta as intended

• el.scrollTop. A browser clamp then can't be double-counted: the settle pass sees the DOM
  is already where it should be and applies ~0. Full unit suite (1320 tests) still passes.

Here's the patch :

Index: src/components/ScrollAdjust.tsx
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
diff --git a/src/components/ScrollAdjust.tsx b/src/components/ScrollAdjust.tsx
--- a/src/components/ScrollAdjust.tsx	(revision 265b013826fa37b608365838b91709b00d39dc08)
+++ b/src/components/ScrollAdjust.tsx	(date 1780913020888)
@@ -49,61 +49,73 @@
     const contentNodeRef = React.useRef<HTMLElement | null>(null);
 
     const callback = React.useCallback(() => {
-        const scrollAdjust = peek$(ctx, "scrollAdjust");
-        const scrollAdjustUserOffset = peek$(ctx, "scrollAdjustUserOffset");
+        const scrollAdjust = peek$(ctx, "scrollAdjust") || 0;
+        const scrollAdjustUserOffset = peek$(ctx, "scrollAdjustUserOffset") || 0;
 
-        const scrollOffset = (scrollAdjust || 0) + (scrollAdjustUserOffset || 0);
-        const scrollDelta = scrollOffset - lastScrollOffsetRef.current;
+        const scrollOffset = scrollAdjust + scrollAdjustUserOffset;
+        const signalDelta = scrollOffset - lastScrollOffsetRef.current;
 
-        if (scrollDelta !== 0) {
+        // Only act when the adjustment signal actually changed (an MVCP / user-offset update).
+        if (signalDelta !== 0) {
             const target = getScrollAdjustTarget(ctx, contentNodeRef.current);
             if (target) {
                 const horizontal = !!ctx.state.props.horizontal;
                 const axis = getScrollAdjustAxis(horizontal);
                 const { contentNode, scrollElement: el } = target;
-                const scrollBy = () => scrollAdjustBy(el, axis.x * scrollDelta, axis.y * scrollDelta);
 
                 contentNodeRef.current = contentNode;
 
-                if (contentNode) {
-                    const prevScroll = horizontal ? el.scrollLeft : el.scrollTop;
-                    const totalSize = contentNode[axis.contentSizeKey];
-                    const viewportSize = el[axis.viewportSizeKey];
-                    const nextScroll = prevScroll + scrollDelta;
-                    const needsTemporaryPadding =
-                        scrollDelta > 0 &&
-                        !ctx.state.adjustingFromInitialMount &&
-                        totalSize < nextScroll + viewportSize;
+                const currentScroll = horizontal ? el.scrollLeft : el.scrollTop;
+                // Reconcile against the live DOM scroll instead of applying the signal delta blindly.
+                // `state.scroll` is the authoritative absolute target (it already includes every
+                // requestAdjust); `scrollAdjustUserOffset` is applied on top of it on web. Applying a
+                // relative delta would double-count any browser scroll clamp that happened since the
+                // last apply — e.g. content shrinking below an over-shot scroll near the end — so we
+                // move the DOM to the intended absolute position instead.
+                const intendedScroll = ctx.state.scroll + scrollAdjustUserOffset;
+                const scrollDelta = intendedScroll - currentScroll;
+                const scrollBy = () => scrollAdjustBy(el, axis.x * scrollDelta, axis.y * scrollDelta);
+
+                if (Math.abs(scrollDelta) > 0.01) {
+                    if (contentNode) {
+                        const totalSize = contentNode[axis.contentSizeKey];
+                        const viewportSize = el[axis.viewportSizeKey];
+                        const nextScroll = currentScroll + scrollDelta;
+                        const needsTemporaryPadding =
+                            scrollDelta > 0 &&
+                            !ctx.state.adjustingFromInitialMount &&
+                            totalSize < nextScroll + viewportSize;
 
-                    if (needsTemporaryPadding) {
-                        // If trying to scroll out of bounds of the scroll element's current size
-                        // it would clamp the scroll and not do the full adjustment. So we need to
-                        // add padding to the scroll element to allow the scroll to complete.
-                        const previousPaddingEnd =
-                            resetPaddingBaselineRef.current ?? contentNode.style[axis.paddingEndProp];
-                        resetPaddingBaselineRef.current = previousPaddingEnd;
-                        const pad = (nextScroll + viewportSize - totalSize) * 2;
-                        contentNode.style[axis.paddingEndProp] = `${pad}px`;
-                        // Force a layout update by reading from DOM
-                        void contentNode.offsetHeight;
+                        if (needsTemporaryPadding) {
+                            // If trying to scroll out of bounds of the scroll element's current size
+                            // it would clamp the scroll and not do the full adjustment. So we need to
+                            // add padding to the scroll element to allow the scroll to complete.
+                            const previousPaddingEnd =
+                                resetPaddingBaselineRef.current ?? contentNode.style[axis.paddingEndProp];
+                            resetPaddingBaselineRef.current = previousPaddingEnd;
+                            const pad = (nextScroll + viewportSize - totalSize) * 2;
+                            contentNode.style[axis.paddingEndProp] = `${pad}px`;
+                            // Force a layout update by reading from DOM
+                            void contentNode.offsetHeight;
 
-                        scrollBy();
-                        // Multiple adjustments can happen in one frame; keep only the latest padding reset.
-                        if (resetPaddingRafRef.current !== undefined) {
-                            cancelAnimationFrame(resetPaddingRafRef.current);
-                        }
+                            scrollBy();
+                            // Multiple adjustments can happen in one frame; keep only the latest padding reset.
+                            if (resetPaddingRafRef.current !== undefined) {
+                                cancelAnimationFrame(resetPaddingRafRef.current);
+                            }
 
-                        // After the scrollBy, revert the temporary end padding.
-                        resetPaddingRafRef.current = requestAnimationFrame(() => {
-                            resetPaddingRafRef.current = undefined;
-                            resetPaddingBaselineRef.current = undefined;
-                            contentNode.style[axis.paddingEndProp] = previousPaddingEnd;
-                        });
-                    } else {
-                        scrollBy();
-                    }
-                } else {
-                    scrollBy();
+                            // After the scrollBy, revert the temporary end padding.
+                            resetPaddingRafRef.current = requestAnimationFrame(() => {
+                                resetPaddingRafRef.current = undefined;
+                                resetPaddingBaselineRef.current = undefined;
+                                contentNode.style[axis.paddingEndProp] = previousPaddingEnd;
+                            });
+                        } else {
+                            scrollBy();
+                        }
+                    } else {
+                        scrollBy();
+                    }
                 }
             }
 

[jmeistrich]

Thanks! This should be fixed in 3.1.0. Please give it a try and let me know if it's still not working right 😀