react-native-safe-area-context

A flexible way to handle safe area, also works on Android and Web!

Getting started

Install the library using either Yarn:

yarn add react-native-safe-area-context

or npm:

npm install --save react-native-safe-area-context

You then need to link the native parts of the library for the platforms you are using.

Linking in React Native >= 0.60

Linking the package is not required anymore with Autolinking.

iOS Platform:

$ npx pod-install

Linking in React Native < 0.60

The easiest way to link the library is using the CLI tool by running this command from the root of your project:

react-native link react-native-safe-area-context

If you can't or don't want to use the CLI tool, you can also manually link the library using the instructions below (click on the arrow to show them):

Manually link the library on iOS

Either follow the instructions in the React Native documentation to manually link the framework or link using Cocoapods by adding this to your Podfile:

pod 'react-native-safe-area-context', :path => '../node_modules/react-native-safe-area-context'

Manually link the library on Android

Make the following changes:

`android/settings.gradle`

include ':react-native-safe-area-context'
project(':react-native-safe-area-context').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-safe-area-context/android')

`android/app/build.gradle`

dependencies {
   ...
   implementation project(':react-native-safe-area-context')
}

`android/app/src/main/.../MainApplication.java`

On top, where imports are:

import com.th3rdwave.safeareacontext.SafeAreaContextPackage;

Add the SafeAreaContextPackage class to your list of exported packages.

@Override
protected List<ReactPackage> getPackages() {
    return Arrays.asList(
            new MainReactPackage(),
            ...
            new SafeAreaContextPackage()
    );
}

Usage

SafeAreaView is a regular View component with the safe area edges applied as padding.

If you set your own padding on the view, it will be added to the padding from the safe area.

If you are targeting web, you must set up SafeAreaProvider in as described in the hooks section. You do not need to for native platforms.

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

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

Props

All props are optional.

`emulateUnlessSupported`

true (default) or false

On iOS 10, emulate the safe area using the status bar height and home indicator sizes.

`edges`

Array of top, right, bottom, and left. Defaults to all.

Sets the edges to apply the safe area insets to.

Hooks

Hooks give you direct access to the safe area insets. This is a more advanced use-case, and might perform worse than SafeAreaView when rotating the device.

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

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

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

You use the useSafeAreaInsets hook to get the insets in the form of { top: number, right: number, bottom: number: number, left: number }.

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

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

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

Usage with consumer api:

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

class ClassComponent extends React.Component {
  render() {
    return (
      <SafeAreaInsetsContext.Consumer>
        {(insets) => <View style={{ paddingTop: insets.top }} />}
      </SafeAreaInsetsContext.Consumer>
    );
  }
}

Web SSR

If you are doing server side rendering on the web you can use initialMetrics to inject insets and frame value based on the device the user has, or simply pass zero values. Since insets measurement is async it will break rendering your page content otherwise.

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 as the initialMetrics prop on the provider as described in Web SSR. 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>
  );
}

Resources

Great article about how this library can be used: https://dev.to/brunolemos/adding-notch-support-to-your-react-native-android-app-3ci3

reactrondev/react-native-safe-area-context