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.

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