[huntie]

Summary

Context

Follow-up to #59194, which pads the content container across the scrollable axis for every contentInsetAdjustmentBehavior except 'never'.

Motivation

Before this diff, 'automatic' and 'scrollableAxes' did the same thing. UIKit's .automatic differs from .scrollableAxes only by a backward-compatibility rule tied to automaticallyAdjustsScrollViewInsets, deprecated since iOS 11.

This diff

Pad across the scrollable axis for 'automatic' and 'always' only, so 'scrollableAxes' applies the safe area insets along the scrollable axis alone, as its name and UIKit's .scrollableAxes say.

Value	Along the scrollable axis	Across it
'never'	No insets	No insets
'scrollableAxes'	UIKit content inset	No insets, as in UIKit
'automatic'	UIKit content inset	Content container padded
'always'	UIKit content inset	Content container padded

• 'scrollableAxes' uses UIKit's .scrollableAxes for the along-axis inset, and is the opt-out for apps that handle the side insets themselves (no React Native cross-axis padding). Point-valued contentContainerStyle padding is still absorbed on edges where UIKit applies an inset.
• The contentInsetAdjustmentBehavior docs now describe each value.

Changelog:
[Internal] - Narrows the cross-axis padding from #59194 to 'automatic' and 'always' before release

Test Plan

RNTester, ScrollView > Content Inset Adjustment Behavior, full screen modal, switching the behavior with the buttons at the top. Before is #59836; after is this PR, both built from source. These are unframed simulator captures.

iPhone Duo folded, scrollableAxes, before	after
Cards stop 20 pt short of the rail, the same as automatic	✅ Cards keep the container's 20 pt and run under the rail, as with UIKit's .scrollableAxes

iPhone 18 Pro landscape, scrollableAxes, before	after
Cards sit clear of both side insets	✅ Cards keep the container's 20 pt from the screen edge, inside the side insets

iPhone Duo folded, after, automatic	after, always
✅ Unchanged: cards clear of the rail	✅ Unchanged: cards clear of the rail

ℹ️ Switching between the values on a running screen updates the layout in both directions.

[huntie]

@huntie-bot If merged before Monday, pick to 0.88 and 0.89 — again citing via an > [!Important] callout that this depends on the other corresponding pick requests for the 2x commits in this stack.

[huntie]

@cipolleschi Updated, thanks

[cipolleschi]

Thanks for this! A few comments inline.

The PR also needs a rebase on top of main before it can land.

One more outside the diff: the safeAreaPadding comment in packages/react-native/ReactCommon/react/renderer/components/scrollview/ScrollContentViewState.h still says the enclosing scroll view sets the pair of edges across its scrollable axis, unconditionally. You updated the matching comment in RCTScrollContentViewComponentView.h to "automatic or always"; could you update this one as well so the two layers agree?

[cipolleschi]

Not introduced by this PR, but more likely to be hit now that 'scrollableAxes' is the suggested opt-out: under 'scrollableAxes' (and 'automatic'), UIKit only applies adjustedContentInset along the axis while it considers the axis scrollable. Absorbing the padding shrinks the content, which can make it fit, so UIKit drops the inset, the padding comes back, and the content becomes scrollable again.

With alwaysBounceVertical={false} and content just taller than the bounds, this can keep flipping through scrollViewDidChangeAdjustedContentInset / layoutSubviews state updates. Could you take a look, or open a follow-up issue to track it?

[huntie-bot]

I see. This seems to happen when padding absorption makes the content just fit, but it predates this PR: the same inset and padding interaction is already in automatic mode on main. We can look at this separately?

[huntie]

@huntie-bot Rebase and address comments.

[huntie-bot]

Decision logged: @huntie decided (13 Nov 2026) to keep the current scrollableAxes behaviour, which absorbs contentContainerStyle padding along the scrollable axis. The docs and PR description will be reworded to describe this accurately, instead of calling it a plain UIKit passthrough. No code change for this thread.