Add an onSafeAreaInsetsChange view prop

[janicduplessis]

Summary:

Prototype, opened for discussion rather than for landing as-is.

SafeAreaView is deprecated in favour of react-native-safe-area-context (per 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 would let both sides go away is native code reporting inset values to JS — today the library's RNCSafeAreaProvider component. This adds that primitive as a view prop instead:

<View
  onSafeAreaInsetsChange={({nativeEvent: {insets, frame}}) => {
    // insets: {top, right, bottom, left}, frame: {x, y, width, height}
  }}
/>

The payload is identical to the library's onInsetsChange, so SafeAreaProvider can swap its native component for a plain View with no API change on its side, and the inset math follows the library's so the semantics match. Insets are relative to the view: a view laid out inside the safe area reports zeros, which is what makes it composable and stops nested providers from double-padding.

Window insets in Dimensions. Dimensions.get('window').safeAreaInsets (and useWindowDimensions) reports the safe area insets of the window using the same native computation — available synchronously at startup and updated through the existing change event. This replaces the library's last native module (initialWindowMetrics); the library-side prototype consuming all of this is appandflow/react-native-safe-area-context#752.

The native SafeAreaView implementations are deleted entirely — the payoff of having the primitive in core. The deprecated public component is now backed by a JS implementation built on the prop, renders identically (verified with the RNTester SafeAreaView example), and works on every platform instead of iOS only. The removal commit is -797/+92 lines: C++ shadow node/state/descriptor, iOS component view, Android view + view manager, codegen spec, and registrations. Two behaviour changes fall out: LogBox, the element inspector and InputAccessoryView now apply safe area padding on Android too (they previously fell back to a plain View), and these surfaces re-render when insets arrive instead of being padded natively.

Synchronous dispatch. The event goes out through EventEmitter::experimental_flushSync as a Discrete event, the same mechanism VirtualView uses: the UI and JS threads block until React has re-rendered, so inset-driven layout is mounted in the frame the insets changed in — first mount included, and on rotation the padding animates with the transition instead of jumping after it. One platform fix was needed: experimental_flushSync only requests a beat, processed at the next EventBeat::induce. Android induces within the frame before drawing, so it is already same-frame; on iOS the beat's run-loop observer runs before Core Animation's commit observer, while the inset events are emitted from layoutSubviews — inside CA's commit cycle — landing them one frame late. AppleEventBeat now additionally schedules an induce in the display phase of the current commit cycle (CA runs layout → display → commit; a zero-sized layer marked dirty during layout gets display after the whole layout pass, before the commit). The experimental_flushSync API is unchanged, iOS becomes structurally the same as Android, and batching falls out: all requests in one layout pass are processed in a single beat — mounting 10 observing views is one ~2.7 ms beat, where a per-callsite flush measured a perfectly linear 10 × ~0.9 ms. The beat semantics are covered by new unit tests (EventBeatTest.cpp).

Cost when unused. The prop is a bool in BaseViewProps (like onLayout); native only observes the safe area when it is set. The only unconditional cost is one ivar check in layoutSubviews/didMoveToWindow, now overridden on RCTViewComponentView — worth a look from someone who profiles that path.

Cost when used. Benchmarked with 50 observing rows inside a ScrollView (the "Scroll benchmark" section of the example), since a view sliding around the screen is the worst case:

• Events fire only when the insets change — the frame is in the payload but not in the trigger, so in-safe-area scrolling emits nothing (verified by event counters on both platforms), and scroll frame times with 50 observers match 0 observers. An earlier frame-triggered iteration emitted per view per frame and sustained a feedback storm (~5,000 events/s on an idle screen, since each synchronous render produces a new frame that re-runs the pre-draw listener); the inset-only trigger makes that loop structurally impossible. Consequence: frame in the payload is "as of the last inset change" — a consumer wanting continuously fresh frames (the library's SafeAreaFrameContext during scrolling) doesn't get them.
• One full synchronous inset event (dispatch → JS render → commit → mount, timed in native, 6 runs): 2.1–3.1 ms iOS, 2.9–3.3 ms Android, debug builds re-rendering a small component; release Hermes should be well below that, and the cost scales with what the app re-renders. Paid per actual inset change, not per frame. Caveat: the synchronous flush drains the whole pending queue, so an inset change coinciding with other queued work (rotation re-rendering every useWindowDimensions consumer) blocks for the full batch — up to ~24 ms in debug during rotation in RNTester.
• The keyboard does not change the reported insets on either platform (iOS safeAreaInsets exclude it for full-screen views; Android excludes ime()) — consistent, matching the library.

Open questions I'd like input on:

• Naming — is onSafeAreaInsetsChange right, and should it ship prefixed (experimental_/unstable_) first?
• Should frame be in the payload at all? The library needs it for SafeAreaFrameContext, but it's derivable with measureInWindow.
• Whether blocking the UI thread on every inset change is acceptable, or whether this should be opt-in per view.
• Legacy architecture is not covered; the prop is Fabric-only.

Changelog:

[GENERAL] [ADDED] - Add an onSafeAreaInsetsChange view prop and Dimensions.get('window').safeAreaInsets, reporting the part of a view / the window covered by the system UI

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 reports zero insets and its frame (iOS left, Android right):

A full screen view padding itself by its own insets — the unpadded (pink) area lines up exactly with the system UI on both platforms, including in landscape:

LogBox (a converted call site) still clears the home indicator, and Dimensions.get('window').safeAreaInsets reports the same values as the prop on both platforms:

Synchronous rendering. The modal in the example opens without the prop; pressing "Apply insets" attaches it. The example renders a loud marker for the in-between state — yellow background while the view observes the safe area but no inset event has been received — so the dispatch timing is directly visible: any displayed yellow frame means the event was not synchronous.

With synchronous dispatch the marker state is committed but never presented. Consecutive captured frames, no yellow frame anywhere in the capture:

Full capture (apply → landscape → portrait), decomposed with ffmpeg and checked frame by frame — zero yellow frames, no stale insets, padding animating with the rotation:

sync-final3.mp4

The same sequence with sync dispatch disabled (plain async dispatchEvent): the marker is presented for one frame on apply, and during rotations the incoming layout renders with the previous orientation's insets, correcting itself over the following frames (scrub the rotations):

async-marker-v.mp4

yarn fantom packages/react-native/Libraries/Components/View/__tests__/ViewSafeAreaInsets-itest.js
yarn fantom packages/react-native/Libraries/Utilities/__tests__/Dimensions-itest.js

Known gaps, noted but not addressed here:

• FabricUIManager's per-frame synchronous-event dedupe can drop a second inset change for the same view landing within one frame; in practice insets don't change twice per frame.
• getGlobalVisibleRect mixes coordinate spaces for partially clipped views (inherited from safe-area-context's implementation).
• Android rotation not exercised (the RNTester activity kept its orientation on my emulator) — the same pre-draw listener drives it.

[github-actions]

Warning

JavaScript API change detected

This PR commits an update to ReactNativeApi.d.ts, indicating a change to React Native's public JavaScript API.

• Please include a clear changelog message.
• This change will be subject to additional review.

This change was flagged as: POTENTIALLY_BREAKING

[mrousavy]

This is amazing!! Been missing this for years