gem-hunter
Language: TypeScript
Native navigation primitives for your React Native app.
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 on iOS is completely handled with auto-linking, if you have ensured pods are installed after adding this module, no other actions are necessary.
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.
Please note that the override code should not be placed inside MainActivityDelegate, but rather directly in MainActivity.
import android.os.Bundle; import com.swmansion.rnscreens.fragment.restoration.RNScreensFragmentFactory; public class MainActivity extends ReactActivity { //...code //react-native-screens override @Override protected void onCreate(Bundle savedInstanceState) { getSupportFragmentManager().setFragmentFactory(new RNScreensFragmentFactory()); super.onCreate(savedInstanceState); } public static class MainActivityDelegate extends ReactActivityDelegate { //...code } }
import android.os.Bundle; import com.swmansion.rnscreens.fragment.restoration.RNScreensFragmentFactory; class MainActivity: ReactActivity() { //...code //react-native-screens override override fun onCreate(savedInstanceState: Bundle?) { supportFragmentManager.fragmentFactory = RNScreensFragmentFactory() super.onCreate(savedInstanceState); } }
For people that must handle cases like this, there is a more detailed discussion of the difficulties in a series of related comments.
Need to use a custom Kotlin version?Since v3.6.0 react-native-screens has been rewritten with Kotlin. Kotlin version used in this library defaults to 1.4.10.
If you need to use a different Kotlin version, set kotlinVersion ext property in your project's android/build.gradle and the library will use this version accordingly:
buildscript {
ext {
...
kotlinVersion = "1.4.10"
}
}
Disclaimer: react-native-screens requires Kotlin 1.3.50 or higher.
Installation on Windows should be completely handled with auto-linking when using React Native Windows 0.63+. For earlier versions, you must manually link the native module.
Screens are already integrated with the React Native's most popular navigation library react-navigation and Expo.
Below we present tables with mapping of the library version to the last supported react-native version. These tables are for the 4.x line of the library. For compat tables
of 3.x line please see readme on the 3.x branch.
Fabric is React Native's default rendering system since 0.76.
Here's a table with summary of supported react-native versions:
| library version | react-native version |
|---|---|
| 4.26.0+ | 0.84.0+ |
| 4.25.0+ | 0.82.0+ |
| 4.19.0+ | 0.81.0+ |
| 4.14.0+ | 0.79.0+ |
| 4.5.0+ | 0.77.0+ |
| 4.0.0+ | 0.76.0+ |
Paper is the legacy rendering system.
Caution
Since version 4.25.0 of this library, it no longer supports the legacy architecture.
Here's a table with summary of supported react-native versions with the legacy architecture turned on:
| library version | react-native version |
|---|---|
| 4.25.0+ | NOT SUPPORTED |
| 4.19.0+ | 0.80.0+ |
| 4.14.0+ | 0.79.0+ |
| 4.9.0+ | 0.76.0+ |
| 4.5.0+ | 0.74.0+ |
| 4.0.0+ | 0.72.0+ |
Caution
JS API of the native stack has been moved from react-native-screens/native-stack to @react-navigation/native-stack since version v6. Currently, native stack v5 (imported from react-native-screens/native-stack) is deprecated and will be removed in the upcoming minor release. react-native-screens v4 will support only @react-navigation/native-stack v7.
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 npx 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.
You have to use React Native 0.68 or higher, react-navigation 5.x or 6.x and react-native-screens >= v3.9.0
Since v3.9.0, react-native-screens comes with experimental support for react-freeze. It uses the React Suspense mechanism to prevent parts of the React component tree from rendering, while keeping its state untouched.
To benefit from this feature, enable it in your entry file (e.g. App.js) with this snippet:
import { enableFreeze } from 'react-native-screens'; enableFreeze(true);
Want to know more? Check out react-freeze README
Found a bug? File an issue here or directly in react-freeze repository.
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.
To take advantage of the native stack navigator primitive for React Navigation that leverages UINavigationController on iOS and Fragment on Android, please refer:
Native iOS component for rendering views straight under the Window. Based on RCTPerfMonitor. You should treat it as a wrapper, providing full-screen, transparent view which receives no props and should ideally render one child View, being the root of its view hierarchy. For the example usage, see https://github.com/software-mansion/react-native-screens/blob/main/apps/src/tests/issue-tests/Test1096.tsx
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.
This library should work out of the box with all existing react-native libraries. If you experience problems with interoperability please report an issue.
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.
Use ScrollView with prop contentInsetAdjustmentBehavior=“automatic” as a main container of the screen and set headerTranslucent: true in screen options.
There are many ways to contribute to this project. See CONTRIBUTING guide for more information. Thank you for your interest in contributing!
React native screens library is licensed under The MIT License.
Since 2012 Software Mansion is a software agency with experience in building web and mobile apps. We are Core React Native Contributors and experts in dealing with all kinds of React Native issues. We can help you build your next dream product – Hire us.