[hsource]

Summary:

Motivation

At Wanderlog, we use a FlatList with negative zIndex so earlier items' bottom shadows can cover later items (by default, later items cover earlier items).

When maintainVisibleContentPosition is enabled, the native helper selects the scroll anchor by scanning content children and picking the first one whose end position exceeds the current scroll offset. Fabric can reorder native children when views use zIndex, so hierarchy order no longer matches layout order. On both iOS and Android, the helper can then anchor to the wrong item, and scroll corrections keep the bottom edge of the visible content fixed instead of the top.

When minIndexForVisible > 0, skipping early items also needs to follow layout order rather than native hierarchy order.

Fix

iOS and Android: Scan all eligible children and select the topmost visible anchor (the smallest end position still below the scroll offset). When minIndexForVisible > 0, sort children by layout position before applying the skip. Also clear the cached anchor when the helper stops listening.

Ported from the approach in #46247, adapted for the current Kotlin helper and Fabric iOS scroll view, and simplified.

Changelog:

[GENERAL] [FIXED] - Fix maintainVisibleContentPosition anchoring to the wrong child when z-index reorders Fabric children

Test Plan:

Automated Android tests

yarn install
cd packages/rn-tester
yarn start
yarn android
maestro test .maestro/flatlist-horizontal-inverted-maintainvisible.yml -e APP_ID=com.facebook.react.uiapp

Automated Fantom tests

yarn install
yarn fantom ScrollView-maintainVisibleContentPosition-itest

Manual test on iOS and Android using RNTester:

1. Open ScrollView → smooth bi-directional content loading
2. Add a few items and scroll so there are items above and below the current item
3. Use Change height at id to change the height of an item in the middle
4. Verify the top edge of that item stays in place, rather than the bottom edge jumping

Android

Before (maintained position relative to bottom)	After (correctly maintains position relative to top)

iOS

Before (maintained position relative to bottom)	After (correctly maintains position relative to top)

[hsource]

This change was made because cloneElement seemed to remove the zIndex, so we instead render items without cloneElement.

While I was at it, I also changed this to a function component.

[hsource]

Note that I realized this is an issue on iOS too! I have an idea for a more universal fix that also ensures minIndexForVisible works correctly too (it currently doesn't)

[hsource]

I just updated the PR to also cover iOS and added more automated testing. I then manually retested on both Android and iOS.

@janicduplessis I know you wrote the previous PR. Let me know what you think of this one!

This is also ready for a review by someone from Meta! @Abbondanzo - it looks like you've reviewed some related logic recently (#57294) - would you maybe be able to review this? I appreciate it!

[hsource]

Here's an easier to review diff of the component rendering changes:

Linkable diff

[chrispader]

Chris's AI wingmate checking in. 🤖

Expensify's chronological LegendList migration needs this fix. I've added a core-view RNTester reproducer in #59360 and a standalone RN 0.88.0 reproducer.

The z-index correction also changes LegendList's zero-sized anchor behavior. With a positioned, zero-sized first child followed by a stationary item wrapper, selecting the smallest visible end position chooses the wrapper. Moving the anchor and rows up 60 leaves the offset at 600 instead of 540, so the visible row shifts. That case already works on RN main.

This small follow-up patch preserves the first eligible zero-sized child when its position exceeds the scroll offset. It carries over the corresponding guard from Expensify's patch. Please keep this case covered alongside the z-index correction.

[Abbondanzo]

@chrispader thanks for the deeper check here and patch

@hsource if you can incorporate Chris' fix and address the merge conflict, happy to pull this in

[chrispader]

@hsource if you can incorporate Chris' fix and address the merge conflict, happy to pull this in

@hsource let me know if i can be of any help in that! 🙌🏼

[hsource]

@Abbondanzo amd @chrispader

I rebased and incorporated the patch! I applied it to iOS as well.

It does feel like a bit of a hackish solution to me: any zero-sized view that happens to be the first subview now gets picked as the anchor without checking anything else, whether or not it was meant as one. It feels like we're doing this to accommodate LegendList because no API exists to do exactly what LegendList wants (maintain a specific index as the anchor all the time).

That said, it's the easiest way to accommodate LegendList's behavior without introducing new APIs, and it matches what already works on main, so I'm OK with it for this PR.

Longer term, I think the ideal API would be a new property on maintainVisibleContentPosition, something like fixedAnchorIndex: number, that lets a list name the anchor explicitly instead of relying on a zero-size heuristic. Happy to follow up on that separately if there's interest.

[hsource]

This and the below code was auto-formatted by ktfmt

[Abbondanzo]

Longer term, I think the ideal API would be a new property on maintainVisibleContentPosition, something like fixedAnchorIndex: number, that lets a list name the anchor explicitly instead of relying on a zero-size heuristic. Happy to follow up on that separately if there's interest.

The zero-size heuristic is there for correctness to what already exists, but I could see the usefulness behind doing something akin to what SwiftUI offers with default scroll anchors rather than making the user keep track of anchor indices. Having to keep track of which index to anchor on and updating it over and over sounds like a potential pain to manage and can fall out of sync since the visibility callbacks are all async.

[meta-codesync]

@Abbondanzo has imported this pull request. If you are a Meta employee, you can view this in D127603701.