FlashList 2.x: maintainVisibleContentPosition bug when initial data does not fills the screen

[ACHP]

Description

When we initialize the flashlist data with only one item, maintainVisibleScrollPosition and startRenderingFromBottom make the list "jump" when adding more items on top. (see video)

Current behavior

In the following video you can see I initialize the chat with only one item, then I click "add more on top" to add more old messages.
During the first render, the initial message appears correctly at the end of the list, but during the second render, it jump to the top/middle of the screen.
When manually scrolling, everything goes back to normal.

RocketSim_Recording_iPhone_16_6.1_2025-12-30_18.57.45.mp4

Expected behavior

Initial item should stay at the bottom of the screen when loading other items on top.

Reproduction

Expo Snack or minimal reproduction link:

https://github.com/ACHP/flash-list/tree/bug-maintain-scroll-position-one-item

Platform

• iOS
• Android
• Web (if applicable)

Environment

React Native info output:

$ npx react-native info
info Fetching system and libraries information...
System:
  OS: macOS 15.5
  CPU: (12) arm64 Apple M3 Pro
  Memory: 135.80 MB / 18.00 GB
  Shell:
    version: "5.9"
    path: /bin/zsh
Binaries:
  Node:
    version: 20.19.5
    path: /Users/alexischappron/.nvm/versions/node/v20.19.5/bin/node
  Yarn:
    version: 1.22.22
    path: /opt/homebrew/bin/yarn
  npm:
    version: 10.8.2
    path: /Users/alexischappron/.nvm/versions/node/v20.19.5/bin/npm
  Watchman: Not Found
Managers:
  CocoaPods:
    version: 1.16.2
    path: /var/folders/12/_ffy101j76zccg89mklrbbdw0000gn/T/frum_86768_1767116592867/bin/pod
SDKs:
  iOS SDK:
    Platforms:
      - DriverKit 24.2
      - iOS 18.2
      - macOS 15.2
      - tvOS 18.2
      - visionOS 2.2
      - watchOS 11.2
  Android SDK:
    API Levels:
      - "23"
      - "25"
      - "28"
      - "29"
      - "30"
      - "31"
      - "33"
      - "34"
      - "35"
      - "36"
    Build Tools:
      - 28.0.3
      - 29.0.2
      - 30.0.2
      - 30.0.3
      - 31.0.0
      - 32.0.0
      - 33.0.0
      - 33.0.1
      - 34.0.0
      - 35.0.0
      - 35.0.1
      - 36.0.0
    System Images:
      - android-24 | ARM 64 v8a
      - android-28 | ARM 64 v8a
      - android-29 | Google APIs ARM 64 v8a
      - android-30 | Google APIs ARM 64 v8a
      - android-30 | Google Play ARM 64 v8a
      - android-31 | Google APIs ARM 64 v8a
      - android-31 | Google Play Intel x86_64 Atom
      - android-32 | Google APIs ARM 64 v8a
      - android-33-ext5 | Google Play ARM 64 v8a
      - android-34 | Google APIs ARM 64 v8a
      - android-35 | ARM 64 v8a
    Android NDK: Not Found
IDEs:
  Android Studio: 2025.1 AI-251.27812.49.2514.14085407
  Xcode:
    version: 16.2/16C5032a
    path: /usr/bin/xcodebuild
Languages:
  Java:
    version: 17.0.10
    path: /Users/alexischappron/.asdf/shims/javac
  Ruby:
    version: 3.4.5
    path: /var/folders/12/_ffy101j76zccg89mklrbbdw0000gn/T/frum_86768_1767116592867/bin/ruby
npmPackages:
  "@react-native-community/cli": Not Found
  react:
    installed: 18.3.1
    wanted: 18.3.1
  react-native:
    installed: 0.76.5
    wanted: 0.76.5
  react-native-macos: Not Found
npmGlobalPackages:
  "*react-native*": Not Found
Android:
  hermesEnabled: Not found
  newArchEnabled: Not found
iOS:
  hermesEnabled: true
  newArchEnabled: true

FlashList version:

Additional context

Checklist

• I've searched existing issues and couldn't find a duplicate
• I've provided a minimal reproduction (Expo Snack preferred)
• I'm using the latest version of @shopify/flash-list
• I've included all required information above

Possible bypass

Using
autoscrollToBottomThreshold: 1 and animateAutoScrollToBottom: false kinda bypass the issue because the list scroll back to the right position immediately. But in a chat app we often wan to use animateAutoScrollToBottom: true, so we need to set it to true once we've loaded enough message for the problem to disapear. And it's a bit hacky.

Probable root cause

The issue occurs because applyOffsetCorrection in useRecyclerViewController.tsx only calculates the difference between the items' layouts (their x or y coordinates). However, when startRenderingFromBottom is enabled, FlashList applies a dynamic marginTop or marginLeft (the "adjustment margin") to the container in ViewHolderCollection.tsx.

https://github.com/ACHP/flash-list/blob/c19e2983918c0e54012dc99b464c018a0aa3986f/src/recyclerview/hooks/useRecyclerViewController.tsx#L161-L165

useRecyclerViewController.tsx

 const applyOffsetCorrection = useCallback(() => {
/*...*/
const diff = horizontal
            ? recyclerViewManager.getLayout(currentIndexOfFirstVisibleItem).x -
              firstVisibleItemLayout.current!.x
            : recyclerViewManager.getLayout(currentIndexOfFirstVisibleItem).y -
              firstVisibleItemLayout.current!.y;
/*...*/

RecyclerView.tsx

<ViewHolderCollection
           /*...*/
            getAdjustmentMargin={() => {
              if (!shouldRenderFromBottom || !recyclerViewManager.hasLayout()) {
                return 0;
              }

              const windowSize = horizontal
                ? recyclerViewManager.getWindowSize().width
                : recyclerViewManager.getWindowSize().height;
              const childContainerSize = horizontal
                ? recyclerViewManager.getChildContainerDimensions().width
                : recyclerViewManager.getChildContainerDimensions().height;

              return Math.max(
                0,
                windowSize -
                  childContainerSize -
                  recyclerViewManager.firstItemOffset
              );
            }}
/>

[huytdps13400]

please help me. I am facing that issue too. @ACHP

[ACHP]

@huytdps13400 for now I'm using this patch:
It tries to re-compute adjustmentMargin before applying new offset correction, it seems to work great on my exemple/debug screen, but I have another problem in my app unfortunately so I might have to find a totally different bypass.

diff --git a/node_modules/@shopify/flash-list/dist/recyclerview/hooks/useRecyclerViewController.js b/node_modules/@shopify/flash-list/dist/recyclerview/hooks/useRecyclerViewController.js
index 64e0631..2baffb2 100644
--- a/node_modules/@shopify/flash-list/dist/recyclerview/hooks/useRecyclerViewController.js
+++ b/node_modules/@shopify/flash-list/dist/recyclerview/hooks/useRecyclerViewController.js
@@ -31,6 +31,7 @@ export function useRecyclerViewController(recyclerViewManager, ref, scrollViewRe
     // Track the first visible item for maintaining scroll position
     const firstVisibleItemKey = useRef(undefined);
     const firstVisibleItemLayout = useRef(undefined);
+    const lastAdjustmentMarginRef = useRef(0);
     // Queue to store callbacks that should be executed after scroll offset updates
     const pendingScrollCallbacks = useRef([]);
     // Handle initial scroll position when the list first loads
@@ -79,14 +80,30 @@ export function useRecyclerViewController(recyclerViewManager, ref, scrollViewRe
      * the user's current view position when new messages are added.
      */
     const applyOffsetCorrection = useCallback(() => {
-        var _a, _b, _c;
-        const { horizontal, data } = recyclerViewManager.props;
+        var _a, _b, _c, _d;
+        const { horizontal, data, maintainVisibleContentPosition } = recyclerViewManager.props;
         // Execute all pending callbacks from previous scroll offset updates
         // This ensures any scroll operations that were waiting for render are completed
         const callbacks = pendingScrollCallbacks.current;
         pendingScrollCallbacks.current = [];
         callbacks.forEach((callback) => callback());
         const currentDataLength = recyclerViewManager.getDataLength();
+        const shouldRenderFromBottom = currentDataLength > 0 &&
+            ((_a = maintainVisibleContentPosition === null || maintainVisibleContentPosition === void 0 ? void 0 : maintainVisibleContentPosition.startRenderingFromBottom) !== null && _a !== void 0 ? _a : false);
+        const calculateAdjustmentMargin = () => {
+            if (!shouldRenderFromBottom || !recyclerViewManager.hasLayout()) {
+                return 0;
+            }
+            const windowSize = horizontal
+                ? recyclerViewManager.getWindowSize().width
+                : recyclerViewManager.getWindowSize().height;
+            const childContainerSize = horizontal
+                ? recyclerViewManager.getChildContainerDimensions().width
+                : recyclerViewManager.getChildContainerDimensions().height;
+            return Math.max(0, windowSize - childContainerSize - recyclerViewManager.firstItemOffset);
+        };
+        const currentAdjustmentMargin = calculateAdjustmentMargin();
+        const marginDiff = currentAdjustmentMargin - lastAdjustmentMarginRef.current;
         if (recyclerViewManager.getIsFirstLayoutComplete() &&
             recyclerViewManager.hasStableDataKeys() &&
             currentDataLength > 0 &&
@@ -94,21 +111,22 @@ export function useRecyclerViewController(recyclerViewManager, ref, scrollViewRe
             const hasDataChanged = currentDataLength !== lastDataLengthRef.current;
             // If we have a tracked first visible item, maintain its position
             if (firstVisibleItemKey.current) {
-                const currentIndexOfFirstVisibleItem = (_a = recyclerViewManager
+                const currentIndexOfFirstVisibleItem = (_b = recyclerViewManager
                     .getEngagedIndices()
                     .findValue((index) => recyclerViewManager.getDataKey(index) ===
-                    firstVisibleItemKey.current)) !== null && _a !== void 0 ? _a : (hasDataChanged
+                    firstVisibleItemKey.current)) !== null && _b !== void 0 ? _b : (hasDataChanged
                     ? data === null || data === void 0 ? void 0 : data.findIndex((item, index) => recyclerViewManager.getDataKey(index) ===
                         firstVisibleItemKey.current)
                     : undefined);
                 if (currentIndexOfFirstVisibleItem !== undefined &&
                     currentIndexOfFirstVisibleItem >= 0) {
                     // Calculate the difference in position and apply the offset
-                    const diff = horizontal
+                    const layoutDiff = horizontal
                         ? recyclerViewManager.getLayout(currentIndexOfFirstVisibleItem).x -
                             firstVisibleItemLayout.current.x
                         : recyclerViewManager.getLayout(currentIndexOfFirstVisibleItem).y -
                             firstVisibleItemLayout.current.y;
+                    const diff = layoutDiff + marginDiff;
                     firstVisibleItemLayout.current = {
                         ...recyclerViewManager.getLayout(currentIndexOfFirstVisibleItem),
                     };
@@ -118,7 +136,7 @@ export function useRecyclerViewController(recyclerViewManager, ref, scrollViewRe
                         // console.log("diff", diff, firstVisibleItemKey.current);
                         if (PlatformConfig.supportsOffsetCorrection) {
                             // console.log("scrollBy", diff);
-                            (_b = scrollAnchorRef.current) === null || _b === void 0 ? void 0 : _b.scrollBy(diff);
+                            (_c = scrollAnchorRef.current) === null || _c === void 0 ? void 0 : _c.scrollBy(diff);
                         }
                         else {
                             const scrollToParams = horizontal
@@ -130,7 +148,7 @@ export function useRecyclerViewController(recyclerViewManager, ref, scrollViewRe
                                     y: recyclerViewManager.getAbsoluteLastScrollOffset() + diff,
                                     animated: false,
                                 };
-                            (_c = scrollViewRef.current) === null || _c === void 0 ? void 0 : _c.scrollTo(scrollToParams);
+                            (_d = scrollViewRef.current) === null || _d === void 0 ? void 0 : _d.scrollTo(scrollToParams);
                         }
                         if (hasDataChanged) {
                             updateScrollOffsetWithCallback(recyclerViewManager.getAbsoluteLastScrollOffset() + diff, () => { });
@@ -145,6 +163,7 @@ export function useRecyclerViewController(recyclerViewManager, ref, scrollViewRe
             computeFirstVisibleIndexForOffsetCorrection();
         }
         lastDataLengthRef.current = recyclerViewManager.getDataLength();
+        lastAdjustmentMarginRef.current = currentAdjustmentMargin;
     }, [
         recyclerViewManager,
         scrollAnchorRef,

[huytdps13400]

maintainVisibleContentPosition={{ disabled: true, }}
I fix solution