[huntie]

Summary

Context

Optional but intended follow-up to #59194.

#59194 fixed the documented behaviour of ScrollView/FlatList contentInsetAdjustmentBehavior by handling safe area padding across the scrollable axis, such as the rail on iPhone Duo and the notch on a regular iPhone in landscape.

Now that this works, there's a further detail on Duo which reveals a bug/misbehaviour with contentInsetAdjustmentBehavior handling and inner content padding.

This diff

Proposes a further update to contentInsetAdjustmentBehavior and how it interacts with padding set by contentContainerStyle.

Key change: Moves from an add padding approach to max of padding or safe area, per edge.

Illustrated — ScrollView with 20px content padding all sides + contentInsetAdjustmentBehavior="auto"

❌ Bug	❌ Bug	➖ Not a bug
List flush against top inset — fixed here	List flush against rail inset — fixed here	List under header, away from top inset unchanged
❗ Breaking fix, where this combination occurs.	✅ Only applies since side inset support added in last PR, so no additional user impact.	✅ This is expected to be the vast majority of use cases for real apps.

The aim is to make React Native's scroll views work intuitively.

• This is a hard thing for most devs to spot and remember to do. To get a high quality result requires negating the extra padding on one edge manually (i.e. Add StatusBar.getVerticalBarEdgeIOS and useVerticalBarEdgeIOS for iPhone Duo #59237).
• Our historic "add padding" handling in iPhone landscape is arguably a bug. From our own ScrollView RNTester demos in landscape, having added horizontal padding beyond the safe area on both sides misaligns the content from relative UI such as the header nav bar.
  • This is also how UIKit treats layout margins against the safe area.

Implementation notes

• A percentage padding still keeps its edge as styled, with no inset (same as before this stack).
• The RNTester full screen example is updated to add a larger 20 pt padding on its content container, with its controls and rows drawn as rounded cards, to show the clamp, plus an "under header" toggle that places a custom header above the scroll view.
• Android is untouched: its scroll view has no safe area handling across the scrollable axis to clamp.

Changelog:
[iOS][Fixed] - ScrollView: contentInsetAdjustmentBehavior now pads content by the larger of the safe area or contentContainerStyle padding. Previously, it added the two.

Test Plan

ReactCommon/react/renderer/components/scrollview/tests/ScrollContentViewTest.cpp

RNTester, ScrollView > Content Inset Adjustment Behavior

iPhone 18 Pro portrait, before	after
⚠️ 20 pt green on every side, including below the status bar inset at the top	✅ Content top sits at the status bar inset, which absorbs the 20 pt

iPhone 18 Pro portrait under a custom header, before	after
✅ The scroll view starts below the header, with no top inset, so the 20 pt applies	✅ Unchanged: with no inset to absorb it, the 20 pt still applies

iPhone 18 Pro landscape, before	after
⚠️ Content sits 20 pt inside both safe area edges	✅ Content sits at both safe area edges, which absorb the 20 pt

iPhone Duo folded, before	after
⚠️ Content stops 20 pt short of the rail: the inset and the padding add	✅ Content sits at the rail, which absorbs the 20 pt; the 20 pt stays on the open side and at the top

[cipolleschi]

Nit: The docs say contentContainerStyle padding counts toward the inset “on every edge,” but percentage padding intentionally bypasses this calculation. Could we qualify this as point-valued padding or mention the percentage-padding exception?

[huntie]

Yeah let me follow this up 👍🏻👍🏻

[cipolleschi]

Thanks for adding the detailed percentage-padding behavior below — that addresses the underlying nuance. One small follow-up: this sentence still says the padding counts toward the inset “on every edge,” which remains slightly over-broad because percentage padding across the scrollable axis intentionally bypasses the safe-area padding. Could we qualify this sentence as point-valued/pixel padding too?

[cipolleschi]

Looks good overall. The inset calculation, RTL handling, native state propagation, and test coverage are sound. I left one non-blocking documentation nit.

[huntie]

@huntie-bot Pick to 0.89 and 0.88 when merged. Assume #59194 is successfully picked first, by explicitly stating this dependency in the pick request with an > [!Important] callout.

[cipolleschi]

Just to set expectations, we can't pick these changes in 0.88 because it will be a breaking change.