react-native-safe-area-context

react-native-safe-area-context is the de-facto standard for reading device safe area insets in React Native apps. It exposes a SafeAreaProvider, a SafeAreaView component, and hooks like useSafeAreaInsets that give you the exact top, bottom, left, and right padding needed to keep your UI clear of notches, status bars, home indicators, and rounded corners.

Unlike the older platform-specific approaches, it works consistently across iOS, Android, web, macOS, and Windows, and supports the New Architecture (Fabric). Because insets are delivered as plain numbers through React context, you can drive layout, animations, and scroll offsets from them with full control instead of relying on an opaque wrapper component.

What You Get

• A SafeAreaProvider that measures the device’s safe area and shares insets and frame through React context.
• useSafeAreaInsets and useSafeAreaFrame hooks that return precise numeric insets and window dimensions.
• A SafeAreaView component with configurable edges and padding/margin modes for declarative safe layouts.
• Cross-platform native implementations for iOS, Android, web, macOS, and Windows, including New Architecture (Fabric) support.
• initialMetrics and a SafeAreaListener for synchronous first render and imperative inset change handling.

Common Use Cases

• Padding a screen’s header and footer so they clear the notch and home indicator on modern phones.
• Positioning floating buttons or toolbars a fixed distance above the bottom safe area.
• Building custom tab bars and navigation headers that adapt to each device’s insets.
• Driving animated values or scroll offsets from the exact inset numbers instead of hardcoded constants.

Under The Hood

Architecture The library splits a thin JavaScript layer from platform-native measurement code. src/SafeAreaContext.tsx defines two React contexts (SafeAreaInsetsContext and SafeAreaFrameContext) and the SafeAreaProvider, which wraps a NativeSafeAreaProvider and listens for an onInsetsChange event to update inset and frame state, memoizing to avoid re-renders when values are unchanged. Platform is resolved through file extensions (NativeSafeAreaProvider.web.tsx, .windows.tsx, .native.ts variants of InitialWindow), and the native side is generated via Fabric codegen (codegenConfig in package.json, specs under src/specs) with implementations in Objective-C/Objective-C++ (ios/), Kotlin/Java (android/), and shared C++ (common/). Consumer hooks read straight from context and throw a descriptive error when no provider is mounted.

Tech Stack Written in TypeScript (strict tsconfig), built with react-native-builder-bob into CommonJS, ES module, and typings outputs. It declares react and react-native as peer dependencies with zero runtime dependencies of its own. Native code targets the New Architecture through React Native codegen; the repo uses Jest with @testing-library/react-native, ESLint, Prettier, clang-format, and Spotless for multi-language formatting.

Code Quality The codebase is small, well-typed, and tested: src/__tests__ contains Jest suites for the context, the view, and initial-window metrics, including snapshot tests. Error handling is explicit (a clear NO_INSETS_ERROR thrown from the hooks), state updates are guarded against redundant renders, and deprecated APIs (useSafeArea, SafeAreaConsumer) are retained with @deprecated markers for backwards compatibility rather than removed abruptly.

API Design The public surface is deliberately minimal and ergonomic. useSafeAreaInsets() returns a plain { top, right, bottom, left } object, SafeAreaView offers declarative edges and mode props, and a withSafeAreaInsets HOC covers class components. Naming is consistent and discoverable, the single index.tsx re-exports everything, and setup requires only wrapping the app in one provider — a low-boilerplate, well-documented developer experience backed by a dedicated docs site.