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

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.

https://github.com/user-attachments/assets/4369b97d-35b3-49ee-9a8a-e8eb4871e313

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

$ 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
              );
            }}
/>

Run the minimal reproduction on the bug-maintain-scroll-position-one-item branch and observe the jump when adding items above a single initial item. Read applyOffsetCorrection in src/recyclerview/hooks/useRecyclerViewController.tsx alongside the adjustment-margin calculation passed to ViewHolderCollection in RecyclerView.tsx. Done means the initial item remains at the bottom when older items are added, including with animated auto-scroll.