Add an experimental_onSafeAreaInsetsChange view prop

[janicduplessis]

Summary:

Reports the part of a view that is covered by the system UI, as a view prop:

<View
  experimental_onSafeAreaInsetsChange={({nativeEvent: {insets}}) => {
    // insets: {top, right, bottom, left}
  }}
/>

SafeAreaView is deprecated in favour of react-native-safe-area-context (react-native-community/discussions-and-proposals#827), but core surfaces like LogBox and the element inspector cannot depend on the library, so core keeps a private copy of the deprecated component alive. The smallest primitive that lets both sides go away is native code reporting inset values to JavaScript — today the library's own RNCSafeAreaProvider component. This adds that primitive as a view prop, so SafeAreaProvider can swap its native component for a plain View.

Insets are relative to the view: one laid out inside the safe area reports zeros. That is what makes the prop composable and stops nested providers from double-padding.

The event is dispatched synchronously through experimental_flushSync, so the layout that depends on the insets is mounted in the frame the insets changed in (on iOS that relies on #58530 for events emitted from layoutSubviews; text re-rendered by them draws correctly once #58632 lands). A full inset event — dispatch, JS render, commit, mount — is about 3 ms in a debug build re-rendering a small component, paid per inset change rather than per frame.

Two things I'd like input on:

• Whether blocking the UI thread on every inset change is acceptable, or should be opt-in per view.
• The cost when unused: a bool in BaseViewProps like onLayout, and a branch on it in layoutSubviews, didMoveToWindow and safeAreaInsetsDidChange on every view. Worth a look from someone who profiles that path. On Android nothing is attached unless the prop is set.

In development, View wraps the handler and warns once per view above ten events in a second. The system UI does not move that often, so a sustained stream means the layout is feeding the insets back into the view's own position — offset by what it reports, it moves out from under the system UI, which changes what it reports. The check is one JavaScript implementation for both platforms and surfaces in LogBox with a stack rather than in logcat.

Changelog:

[GENERAL] [ADDED] - Add an experimental_onSafeAreaInsetsChange view prop, reporting the part of a view that is covered by the system UI, with a development warning for views that report their insets in a loop

Test Plan:

RNTester, new "Safe area insets" example, on an iPhone 17 Pro simulator and an Android 16 emulator: a view inside the safe area reads zero insets; a full screen view padding itself by its own insets lines up with the system UI in portrait and landscape on both platforms; the scroll benchmark counts events on both platforms. Screenshots and the synchronous-dispatch frame captures are in #57967, the prototype this splits. The example also grows the mistake the warning catches — a view positioned by the insets it reports — behind a button, and it logs once.

Fantom (ViewSafeAreaInsets-itest.js, ViewSafeAreaInsetsWarning-itest.js):

• Delivery and opt-in — the event reaches the handler with the insets; a view without the prop is never its target.
• View flattening — a layout-only view is flattened away; the same view is kept once it has the prop, since observing needs a host view (asserted both ways).
• Warning — silence at a plausible rate (20 changes 200 ms apart), one warning per view under a loop, per-view counting, and the handler still receiving its event, with a mocked clock.

On device:

• View recycling — scrolling a long list of observing rows in and out; recycled rows report their own insets, not a previous occupant's, on both platforms.
• Clipped Android views — rows scrolled out of a ScrollView emit nothing instead of garbage overlap values (event counters in the scroll benchmark).
• Multi-scene iPad — with UIApplicationSupportsMultipleScenes enabled in a local RNTester build (it ships off): two windows, two React instances, one shared key window, correct per-window insets across tiling, fullscreen, rotation and keyboard.

Known gaps, not addressed here:

• FabricUIManager's per-frame synchronous-event dedupe can drop a second inset change for the same view within one frame; in practice insets don't change twice per frame.
• getGlobalVisibleRect mixes coordinate spaces for partially clipped views, inherited from the library's implementation.
• On iOS, a mount that runs inside the display phase (a synchronous inset event processed from layout) and resizes another observing view leaves that view's layoutSubviews for the next transaction, so its event lands a frame late. It needs one observer's synchronous render to resize a second observer; I have not hit it.
• The loop warning only covers View. The prop is on BaseViewProps, so Text, Image and ScrollView accept it too; View is where it is used in practice.
• The loop warning's heuristic (more than ten events in a second) also fires for a view dragged slowly across a system-bar band, which is a legitimate stream. I have not seen it in practice; a threshold on alternating values would distinguish the two if it turns out to matter.

---

Stack — split out of #57967, which stays open as the prototype and design discussion. GitHub will not take a fork branch as a pull request base, so each of these targets main and its diff contains the ones below it until they merge. Each PR is one commit on top of the previous one. The display-phase event beat this builds on landed as #58530. #58632 is a standalone fix for text drawn from a display-phase mount, which the prop exposes on rotation.

This is the bottom of the stack, so its diff is already just this change.

👉 1. #58109 — Add an experimental_onSafeAreaInsetsChange view prop
2. #58110 — Report the window safe area insets through Dimensions
3. #58112 — Render the internal SafeAreaView from the safe area insets prop
4. #58113 — Remove the native SafeAreaView and the deprecated public export

[meta-codesync]

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

[janicduplessis]

Re-ran the device checks from the test plan on this commit (f5d8d36, since rebased onto current main as 60dae49 — sentinel ivar, Android first-emit deferred to pre-draw, insets-only payload). iPhone 17 Pro simulator and an Android 16 emulator. The Android column is the one to look at: its first emit now goes through the pre-draw listener instead of the prop setter, and rotation was the one case the prototype never exercised.

A view inside the safe area reads zero insets

iOS	Android

Full screen view padded by its own insets — the pink (unpadded) area lines up with the system UI

Portrait, then landscape; in landscape the top inset follows the notch / status bar to the side, and the portrait values read back correctly after rotating back.

iOS top: 62, bottom: 34	Android top: 48.76, bottom: 24

iOS right: 62, bottom: 20, left: 62	Android top: 24, right: 48.76, bottom: 24

The iOS landscape capture is from a build with #58632 applied: re-taking it showed the readout text clipped at its previous width after rotation — a stale paragraph drawing frame when the mount runs in the display phase, which that standalone PR fixes.

Synchronous dispatch, frame by frame

Apply insets → rotate → rotate back. The example shows a yellow marker while a view observes the safe area but has not received an inset event yet, so any presented marker frame means the dispatch was not synchronous. Every frame of each recording was scanned for the marker color.

iOS — 828 frames, rotations at frames 194 and 523, 0 marker frames

marker.mp4

Android — 194 frames, rotations at frames 107 and 183, 0 marker frames

a-marker.mp4

Loop warning

The example's deliberately mispositioned view (offset by the insets it reports) loops; LogBox shows one warning and it stays at one.

iOS — one warning at 5,508 events, still one at 7,140	Android — one warning; logcat has fired more than 10 times in 1000ms exactly once after 3 s

Two things worth knowing. The loop runs at a few thousand events/s on iOS but a few hundred on Android — Android's is bounded by the pre-draw cadence (one emit per frame), iOS's re-layout cycles faster; both are well past the warning threshold. And the Android recording is a 216×480 downscale from the tool, coarser than the iOS one, but the modal's pink background is clearly detectable at that size (7,400 px in a mid frame), so the yellow marker — a larger, more saturated block — would have been too; the zero is real.

[meta-codesync]

@Abbondanzo merged this pull request in 8d658f4.