Skip to content

Support the IntersectionObserver scrollMargin option - #60153

Open
rubennorte wants to merge 1 commit into
react:mainfrom
rubennorte:intersection-observer-scroll-margin
Open

rubennorte wants to merge 1 commit into
react:mainfrom
rubennorte:intersection-observer-scroll-margin

Conversation

@rubennorte

Copy link
Copy Markdown
Member

Note

Stacked on #60152, which this PR includes. Only the top commit (feat: support the IntersectionObserver scrollMargin option) is new here.

Summary:

rootMargin only dilates the root intersection rectangle, so it can't reveal a target hidden inside an intermediate scroll container. In the spec, that's scrollMargin's job: it dilates the clip rect of every scrollport on the path from the root to the target, and the root's own rect when the root is scrollable. A typical use is prefetching data or images for list items before they scroll into view.

Until now, scrollMargin was rejected: the constructor threw if 'scrollMargin' in options, and the getter always threw.

Only scroll containers clip, and only their clip rects are dilated. RN's clip walk used to clip at every node, including the target itself and overflow: visible ancestors (to their content bounds). That's a no-op without margins, but not with them:

  • Dilating those clips would shrink the target for negative (or mixed-sign) margins.
  • Not dilating them would let a visible node re-clip content that a dilated scroll container below it revealed, e.g. the content container between two nested ScrollViews.

So the walk now only clips at scroll containers, and never dilates the measured node's own clip, since the spec starts the walk at its containing block. overflowInset can't identify scroll containers (it's also zero for a visible node whose children fit), and react/renderer/core can't see Yoga styles. So LayoutableShadowNode gains a virtual isScrollContainer(), which defaults to false and which YogaLayoutableShadowNode overrides to return whether overflow != visible. Only IntersectionObserver uses this clipping mode.

Scrollable explicit roots. Per spec, "both the scrollMargin and the rootMargin are applied to a scrollable intersection root's rectangle". When the explicit root is a scroll container, the rect targets are clipped against is also dilated by scrollMargin, with percentages resolved against the undilated root. rootBounds is the root intersection rectangle, which only rootMargin dilates, so it's unaffected.

Changes:

  • MarginValue moves from IntersectionObserver.h to RectangleEdges.h, because react/renderer/core can't depend on observers/intersection. It gains EdgeMargins and resolveEdgeMargins(), which replace the index-based std::vector<MarginValue> with named edges and retire calculateRootMarginInsets.
  • LayoutInspectingPolicy gains std::optional<EdgeMargins> clipMargin. The margins are passed unresolved, because percentages must resolve against each individual scrollport.
  • enableOverflowClipping only clips at scroll containers.
  • LayoutableShadowNode::isScrollContainer(), overridden by YogaLayoutableShadowNode.
  • IntersectionObserver applies scrollMargin to a scrollable explicit root's clip rect.
  • parseNormalizedRootMargin becomes parseNormalizedMargin, returning std::optional<EdgeMargins>, and is shared by both options.
  • JS: scrollMargin is added to IntersectionObserverInit, the throws are removed, and normalizeRootMargin becomes normalizeMargin(value, name) so errors name the right property.
  • RNTester: a prefetching example with a toggle between rootMargin and scrollMargin. It reports items of a ScrollView within 500px of the viewport, showing that only scrollMargin can see past the ScrollView.

One deviation from the spec, inherited from the existing rootMargin code: percentages on the vertical edges resolve against height, while the spec resolves all four against width.

Changelog:

[GENERAL] [ADDED] - Support the scrollMargin option in IntersectionObserver

Test Plan:

New Fantom tests cover parsing and the getter, plus behaviour:

  • revealing a target past an intermediate ScrollView, with partial and insufficient margins
  • percentages resolved per scrollport
  • negative values, including not affecting overflow: visible ancestors or the target itself
  • overflow: hidden ancestors
  • scrollable and non-scrollable explicit roots, including combination with rootMargin and percentage resolution against the undilated root
  • nested ScrollViews
  • horizontal edges, and the top edge after scrolling
  • composition with rootMargin on the implicit root
yarn fantom packages/react-native/src/private/webapis/intersectionobserver/

138 passed, 1 skipped. With the C++ clipping changes reverted, the 5 negative-margin and scrollable-root tests fail, as expected.

yarn flow-check
yarn lint

Clean.

Manually verified the RNTester example (IntersectionObserver → "IntersectionObserver scrollMargin Prefetch Example") on an iOS simulator: with rootMargin, only items actually visible in the ScrollView are reported; with scrollMargin, items ahead of the scrollport are reported before they scroll into view.

Not done yet: the C++ API snapshots (scripts/cxx-api/api-snapshots/*.api). I couldn't reproduce CI's Doxygen 1.16.1 output locally, so they'll be taken from this PR's validate_cxx_api_snapshots run. This PR is a draft until then.

@meta-cla meta-cla Bot added the CLA Signed This label is managed by the Facebook bot. Authors need to sign the CLA before a PR can be reviewed. label Nov 19, 2026
@rubennorte
rubennorte force-pushed the intersection-observer-scroll-margin branch 2 times, most recently from 8236222 to f2d860b Compare November 19, 2026 17:13
Summary:
`rootMargin` only dilates the root intersection rectangle, so it cannot
reveal a target hidden inside an intermediate scroll container. Per spec
that is `scrollMargin`'s job: it dilates the clip rect of every scrollport
on the path from the root to the target, and of the root itself when the
root is scrollable.

Until now `scrollMargin` was explicitly rejected — the constructor threw on
`'scrollMargin' in options` and the getter always threw.

D117876568 (react#58177) did the groundwork by adding `clipSpecifiedAncestor` and
excluding the observation root from the ancestor clip walk, matching the
spec's "while container is not root" loop.

Per spec, only nodes with a content clip clip the target, and only scroll
containers have their clip rects dilated. RN's clip walk used to clip at
every node, including the target itself and `overflow: visible` ancestors
(to their content bounds). That is a no-op without margins, but not with
them: dilating those clips shrinks the target for negative (or mixed-sign)
margins, and not dilating them lets a `visible` node re-clip content that a
dilated scroll container below it revealed (e.g. the content container
between two nested ScrollViews). So the walk now only clips at nodes with a
content clip, only dilates scroll containers, and never dilates the
measured node's own clip, since the spec starts the walk at its containing
block. `overflowInset` cannot identify these nodes (it is also zero for a
`visible` node whose children fit), and `react/renderer/core` cannot see
Yoga styles, so `LayoutableShadowNode` gains virtual `hasContentClip()` and
`isScrollContainer()` (both default `false`). `YogaLayoutableShadowNode`
returns `overflow != visible` for the former and `overflow` is `hidden` or
`scroll` for the latter. They're the same set today, but CSS
`overflow: clip` is a content clip without being a scroll container, and
`isScrollContainer()` uses an exhaustive switch so new `overflow` values
must be classified explicitly. Only IntersectionObserver uses this clipping
mode.

Per spec, "both the scrollMargin and the rootMargin are applied to a
scrollable intersection root's rectangle". The rect targets are clipped
against is therefore further dilated by `scrollMargin` when the explicit
root is a scroll container, with percentages resolved against the
undilated root. `rootBounds` is the root intersection rectangle, which only
`rootMargin` dilates, so it is unaffected.

Changes:
- `MarginValue` moves from `IntersectionObserver.h` to `RectangleEdges.h`
  (`react/renderer/core` cannot depend on `observers/intersection`), gaining
  `EdgeMargins` and `resolveEdgeMargins()`. This replaces the index-based
  `std::vector<MarginValue>` with named edges and retires
  `calculateRootMarginInsets`.
- `LayoutInspectingPolicy` gains `std::optional<EdgeMargins> clipMargin`,
  applied to scroll-container ancestors only. The margins travel unresolved
  because percentages must resolve against each individual scrollport.
- `enableOverflowClipping` only clips at nodes with a content clip.
- `LayoutableShadowNode::hasContentClip()` and `isScrollContainer()`,
  overridden by `YogaLayoutableShadowNode`.
- `IntersectionObserver` applies `scrollMargin` to a scrollable explicit
  root's clip rect.
- `parseNormalizedRootMargin` becomes `parseNormalizedMargin`, returning
  `std::optional<EdgeMargins>` and shared by both options.
- JS: `scrollMargin` added to `IntersectionObserverInit`, the throws are
  removed, and `normalizeRootMargin` becomes `normalizeMargin(value, name)`
  so errors name the right property.
- RNTester: a prefetching example (toggle between `rootMargin` and
  `scrollMargin`, reporting items of a ScrollView within 500px of the
  viewport) showing that only `scrollMargin` can see past the ScrollView.

One deviation, inherited from the existing `rootMargin` code: percentages
on the vertical edges resolve against height (the spec resolves all four
against width).

Changelog:
[GENERAL] [ADDED] - Support the `scrollMargin` option in IntersectionObserver

Test Plan:
New Fantom tests cover parsing and the getter, plus behaviour: revealing a
target past an intermediate ScrollView, partial and insufficient margins,
percentages resolved per scrollport, negative values, negative values not
affecting `overflow: visible` ancestors or the target itself,
`overflow: hidden` ancestors, scrollable and non-scrollable explicit roots
(including combination with `rootMargin` and percentage resolution against
the undilated root), nested ScrollViews, horizontal edges, the top edge
after scrolling, and composition with `rootMargin` on the implicit root.

```
yarn fantom packages/react-native/src/private/webapis/intersectionobserver/
```
All tests pass. With the C++ changes from the review fixes reverted, the
negative-margin and scrollable-root tests fail, as expected.

```
yarn flow-check
yarn lint
```
Clean.

Manually verified the RNTester example on an iOS simulator.

The `scripts/cxx-api/api-snapshots/*.api` files were taken from CI's
`validate_cxx_api_snapshots` run (Doxygen 1.16.1); the only changes are the
new public symbols above and the codegen'd `scrollMargin` option.
@rubennorte
rubennorte force-pushed the intersection-observer-scroll-margin branch from f2d860b to d64a9d0 Compare November 19, 2026 18:41
@rubennorte
rubennorte marked this pull request as ready for review November 19, 2026 18:42
@meta-codesync

meta-codesync Bot commented Nov 19, 2026

Copy link
Copy Markdown

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

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

CLA Signed This label is managed by the Facebook bot. Authors need to sign the CLA before a PR can be reviewed. p: Facebook Partner: Facebook Partner

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant