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 deliberately identical to the library's onInsetsChange, so SafeAreaProvider can swap its native component for a plain View with no API change on its side. Insets are relative to the view: a view laid out inside the safe area reports zeros, which is what makes it composable and what stops nested providers from double-padding. The inset math follows the library's (UIView.safeAreaInsets on iOS; root window systemBars() | displayCutout() insets clipped to the view's rect on Android) so the semantics match.

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

Every use of the deprecated SafeAreaView inside core is replaced with a JS SafeAreaView built on the prop. Two behaviour changes fall out of that:

• LogBox, the element inspector and InputAccessoryView now apply safe area padding on Android too — they previously fell back to a plain View, since the native SafeAreaView was iOS-only. Relative insets mean this can't double-pad a surface that is already inside the safe area.
• LogBox surfaces re-render when the insets arrive, instead of being padded natively without JS involvement.

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 the layout that depends on the insets is mounted in the frame the insets changed in. That is the part the library cannot do today: rotating the device currently shows one frame with the old padding.

Cost when unused. The prop is a bool in BaseViewProps (like onLayout), and native only observes the safe area when it is set — a UIView that doesn't set it never computes insets, and an Android view never gets a pre-draw listener. iOS pays for one ivar check in layoutSubviews/didMoveToWindow, which are now overridden on RCTViewComponentView; that's the only unconditional cost I could not avoid, and it's worth a look from someone who profiles this path.

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 laid out inside the safe area reports zero insets and its real frame in window coordinates (iOS left, Android right):

A full screen view padding itself by its own insets — the unpadded (pink) area lines up exactly with the status bar / home indicator / gesture bar on both platforms, and on iOS the padding follows rotation:

The LogBox notification container, one of the converted call sites, still clears the home indicator:

Dimensions.get('window').safeAreaInsets reports the same values as the prop on both platforms:

Synchronous rendering — frame-by-frame validation. Screen recordings of the modal presenting and (on iOS) rotating, decomposed with ffmpeg and inspected frame by frame: on both platforms the modal's first visible frames already carry the inset padding while it is still animating in, and on iOS the mid-rotation animation frames already show the new orientation's insets. No frame anywhere shows content with stale insets — which is the artifact this dispatch mode exists to eliminate. The recordings (iOS: modal → landscape → portrait → close; Android: modal presenting):

ios-sync-trimmed.mp4

android-insets2.mp4

As a negative control, the same capture with sync dispatch disabled (plain async dispatchEvent, same build otherwise): during rotation the incoming layout renders with the previous orientation's insets and keeps correcting itself for ~13 frames after the animation — content visibly sits under the notch. Mid-rotation frame with sync (left) vs async (right):

ios-async-trimmed.mp4

(Modal presentation does not visibly flicker even async — the entrance animation masks the one-frame delay on both platforms. Rotation is where async breaks.)

First mount. Probing with a full-bleed view mounted with no modal and no animation initially showed one unpadded frame even with sync dispatch — because experimental_flushSync only requests a synchronous beat: the queue is still processed at the next EventBeat::induce, one frame boundary later. Async, for reference (left: before mount, middle: the flicker frame, right: padded):

The last commit closes this: an opt-in immediate mode on experimental_flushSync processes the queue at the call site. The emit happens during the layout pass of the frame, the resulting React commit mounts inline through the mounting manager's existing follow-up-transaction loop, and the padding is part of the first presented frame. Re-running the same probe with null initial insets: zero unpadded frames — the sync event alone now covers first mount too. Existing experimental_flushSync callers (VirtualView, Android's dispatchEventSynchronously) are unchanged.

Dimensions.get('window').safeAreaInsets remains useful as the zero-native-roundtrip seed (the internal SafeAreaView uses it, and it is what makes initialWindowMetrics in react-native-safe-area-context free), and a shadow-node-level inset mechanism could still be discussed as the C++-only endgame — but neither is required for flicker-free first mount anymore.

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

New Fantom tests — the event payload reaching JS, the prop reaching C++ props, the internal SafeAreaView turning insets into padding, and the physical-pixel scaling of the Dimensions insets.

Not exercised: rotation on Android (the RNTester activity kept its orientation on my emulator) — the same pre-draw listener drives it, but I have not seen it happen.

[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