react-native-screens

What is react-native-screens?

The react-native-screens package provides native primitives to manage and optimize navigation and screen transitions in React Native applications. It aims to improve performance by using native navigation components.

What are react-native-screens's main functionalities?

Native Stack Navigator

This feature allows you to create a stack navigator using native components, which can improve performance and provide a more seamless user experience.

import { createNativeStackNavigator } from 'react-native-screens/native-stack';
import { NavigationContainer } from '@react-navigation/native';
import HomeScreen from './HomeScreen';
import DetailsScreen from './DetailsScreen';

const Stack = createNativeStackNavigator();

function App() {
  return (
    <NavigationContainer>
      <Stack.Navigator>
        <Stack.Screen name="Home" component={HomeScreen} />
        <Stack.Screen name="Details" component={DetailsScreen} />
      </Stack.Navigator>
    </NavigationContainer>
  );
}

export default App;

Screen Component

The Screen and ScreenContainer components allow you to manage screens more efficiently by leveraging native screen management, which can lead to better performance.

import { Screen, ScreenContainer } from 'react-native-screens';
import { View, Text } from 'react-native';

function MyScreen() {
  return (
    <Screen>
      <View>
        <Text>My Screen Content</Text>
      </View>
    </Screen>
  );
}

function App() {
  return (
    <ScreenContainer>
      <MyScreen />
    </ScreenContainer>
  );
}

export default App;

Screen Lifecycle Methods

This feature allows you to use lifecycle methods to detect when a screen is focused or unfocused, enabling you to perform actions like data fetching or cleanup.

import { useFocusEffect } from '@react-navigation/native';
import { useCallback } from 'react';
import { View, Text } from 'react-native';

function MyScreen() {
  useFocusEffect(
    useCallback(() => {
      console.log('Screen is focused');
      return () => {
        console.log('Screen is unfocused');
      };
    }, [])
  );

  return (
    <View>
      <Text>My Screen Content</Text>
    </View>
  );
}

export default MyScreen;

Other packages similar to react-native-screens

react-navigation

React Navigation is a popular library for routing and navigation in React Native applications. It provides a wide range of navigators, including stack, tab, and drawer navigators. While react-native-screens focuses on optimizing performance with native components, React Navigation offers a more comprehensive set of features and is highly customizable.

react-native-navigation

React Native Navigation by Wix is another powerful navigation library that provides native navigation components. It offers a more native feel and performance compared to React Navigation but can be more complex to set up. It is similar to react-native-screens in its focus on native performance but provides a more extensive set of features.

README

This project aims to expose native navigation container components to React Native. It is not designed to be used as a standalone library but rather as a dependency of a full-featured navigation library.

Installation

iOS

Installation on iOS should be completely handled with auto-linking, if you have ensured pods are installed after adding this module, no other actions should be necessary

Android

On Android the View state is not persisted consistently across Activity restarts, which can lead to crashes in those cases. It is recommended to override the native Android method called on Activity restarts in your main Activity, to avoid these crashes.

For most people using an app built from the react-native template, that means editing MainActivity.java, likely located in android/app/src/main/java/<your package name>/MainActivity.java

You should add this code, which specifically discards any Activity state persisted during the Activity restart process, to avoid inconsistencies that lead to crashes.

import android.os.Bundle;

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(null);
}

For people that must handle cases like this, there is a more detailed discussion of the difficulties in a series of related comments.

How can I take advantage of that?

Screens are already integrated with the React Native's most popular navigation library react-navigation and Expo.

Supported react-native version

version	react-native version
3.0.0+	0.62.0+
2.0.0+	0.60.0+

Usage with react-navigation

Screens support is built into react-navigation starting from version 2.14.0 for all the different navigator types (stack, tab, drawer, etc).

To configure react-navigation to use screens instead of plain RN Views for rendering screen views, simply add this library as a dependency to your project:

# bare React Native project
yarn add react-native-screens

# if you use Expo managed workflow
expo install react-native-screens

Just make sure that the version of react-navigation you are using is 2.14.0 or higher.

You are all set 🎉 – when screens are enabled in your application code react-navigation will automatically use them instead of relying on plain React Native Views.

Disabling react-native-screens

If, for whatever reason, you'd like to disable native screens support and use plain React Native Views add the following code in your entry file (e.g. App.js):

import { enableScreens } from 'react-native-screens';

enableScreens(false);

You can also disable the usage of native screens per navigator with detachInactiveScreens.

Using createNativeStackNavigator with React Navigation

To take advantage of the native stack navigator primitive for React Navigation that leverages UINavigationController on iOS and Fragment on Android, please refer:

• for React Navigation >= v5 to the README in react-native-screens/native-stack
• for older versions to the README in react-native-screens/createNativeStackNavigator

Interop with react-native-navigation

React-native-navigation library already uses native containers for rendering navigation scenes so wrapping these scenes with <ScreenContainer> or <Screen> component does not provide any benefits. Yet if you would like to build a component that uses screens primitives under the hood (for example a view pager component) it is safe to use <ScreenContainer> and <Screen> components for that as these work out of the box when rendered on react-native-navigation scenes.

Interop with other libraries

This library should work out of the box with all existing react-native libraries. If you experience problems with interoperability please report an issue.

Guide for navigation library authors

If you are building a navigation library you may want to use react-native-screens to have control over which parts of the React component tree are attached to the native view hierarchy. To do that, react-native-screens provides you with the components documented here.

Contributing

There are many ways to contribute to this project. See CONTRIBUTING guide for more information. Thank you for your interest in contributing!

License

React native screens library is licensed under The MIT License.

Credits

This project is supported by amazing people from Expo.io and Software Mansion