This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 58).

react-native-safe-area-context provides a flexible API for accessing device safe area inset information. This allows you to position your content appropriately around notches, status bars, home indicators, and other such device and operating system interface elements. It also provides a SafeAreaView component that you can use in place of View to automatically inset your views to account for safe areas.

Installation

If you are installing this in an existing React Native app, make sure to install expo in your project. Then, follow the installation instructions provided in the library's README or documentation.

API

import {
  SafeAreaView,
  SafeAreaProvider,
  SafeAreaInsetsContext,
  useSafeAreaInsets,
} from 'react-native-safe-area-context';

Components

import { SafeAreaView } from 'react-native-safe-area-context';

function SomeComponent() {
  return (
    <SafeAreaView>
      <View />
    </SafeAreaView>
  );
}

Hooks

import { useSafeAreaInsets } from 'react-native-safe-area-context';

function HookComponent() {
  const insets = useSafeAreaInsets();

  return <View style={{ paddingTop: insets.top }} />;
}

Types

Guides

Context

Expo Router sets up safe area context automatically. On web, useSafeAreaInsets() and useSafeAreaFrame() return zero values under Expo Router's provider. SafeAreaView does not add safe-area spacing. This applies to all web rendering modes. Android and iOS behavior is unchanged.

Use CSS for web safe-area spacing.

Without Expo Router, add SafeAreaProvider in your app root component when using the library's components or hooks. This provider supports web measurements, but CSS remains the recommended approach for web spacing.

You may need to add it in other places too, including at the root of any modals any routes when using react-native-screen.

import { SafeAreaProvider } from 'react-native-safe-area-context';

function App() {
  return <SafeAreaProvider>...</SafeAreaProvider>;
}

Then, you can use useSafeAreaInsets() hook and also consumer API to access inset data:

import { SafeAreaInsetsContext } from 'react-native-safe-area-context';

function Component() {
  return (
    <SafeAreaInsetsContext.Consumer>
      {insets => <View style={{ paddingTop: insets.top }} />}
    </SafeAreaInsetsContext.Consumer>
  );
}

Optimization

If you can, use SafeAreaView. It's implemented natively so when rotating the device, there is no delay from the asynchronous bridge.

To speed up the initial render, you can import initialWindowMetrics from this package and set it as the initialMetrics prop on the provider as shown below. You cannot do this if your provider remounts, or you are using react-native-navigation.

import { SafeAreaProvider, initialWindowMetrics } from 'react-native-safe-area-context';

function App() {
  return <SafeAreaProvider initialMetrics={initialWindowMetrics}>...</SafeAreaProvider>;
}

Web SSR

For server-side rendering (SSR), follow the web stylesheet setup and hydration guidance.

Platform-specific safe-area spacing

Android and iOS

Use SafeAreaView or the useSafeAreaInsets() hook for native safe-area spacing. The hook provides inset values you can apply to a view:

import { useSafeAreaInsets } from 'react-native-safe-area-context';

function App() {
  const insets = useSafeAreaInsets();
  return (
    <View
      style={{
        paddingTop: insets.top,
        paddingLeft: insets.left,
        paddingBottom: insets.bottom,
        paddingRight: insets.right,
      }}
    />
  );
}

Web

Use CSS environment variables for web safe-area spacing, including in apps that also target Android and iOS. See the CSS example.