repository·main·Indexed 25 days ago
https://github.com/software-mansion/react-native-screensNative navigation primitives for React Native that expose native navigation container components to provide optimized screen rendering for iOS, Android, and other platforms. It is primarily intended as a dependency for navigation libraries like react-navigation. The library includes components such as ScreenContainer, Screen, ScreenStack, and ScreenStackItem to manage native view attachment and platform-native stack navigation.
To use experimental support for react-freeze (which uses React Suspense to prevent parts of the component tree from rendering while keeping state untouched), call enableFreeze(true) in your entry file (e.g., App.js).
Requirements:
react-navigation 5.x or 6.xreact-native-screens >= v3.9.0import { enableFreeze } from 'react-native-screens';
enableFreeze(true);On Android, to prevent crashes during Activity restarts, override the onCreate method in your MainActivity.kt to set the fragmentFactory using RNScreensFragmentFactory.
Note: The override must be placed directly in MainActivity, not inside MainActivityDelegate.
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);
}
}If you need to disable native screens support and revert to using plain React Native Views, call enableScreens(false) in your entry file (e.g., App.js).
import { enableScreens } from 'react-native-screens';
enableScreens(false);LifecycleObserver interface. To receive these updates within react-native-screens, you must register the view using LifecycleHelper.register and ensure you call LifecycleHelper.unregister before the view is destroyed/dropped.For projects using react-native-windows version 0.63 or later, you can use autolinking. Simply install the package via npm.
npm i react-native-screens --saveOn Android, View state may not persist consistently across Activity restarts, which can cause crashes. To avoid this, you must override the onCreate method in your MainActivity (located at android/app/src/main/java/<your package name>/MainActivity.java or .kt) to discard persisted Activity state using RNScreensFragmentFactory.
Note: The override must be placed directly in MainActivity, not inside MainActivityDelegate.
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
}
}To use react-native-screens in a Fabric-enabled application, follow these steps based on your platform:
react-native-screens to your project.rbenv exec bundle installrbenv exec bundle exec pod installrbenv exec bundle install
rbenv exec bundle exec pod installInstall react-native-screens as a dependency to enable native navigation container components. It is designed to be used with full-featured navigation libraries like react-navigation rather than as a standalone library.
For bare React Native projects:
yarn add react-native-screensFor Expo managed workflow:
npx expo install react-native-screensTo set up the FabricExample project, you must install dependencies in both the repository root and the specific example directory.
yarn install.FabricExample directory and run yarn install.yarn install
cd FabricExample
yarn installIf you are building a navigation library, use <ScreenContainer/> to control which parts of the React component tree are attached to the native view hierarchy.
<ScreenContainer/> acts as a container for one or more <Screen/> components. It monitors the activityState property of its children to decide which screens should be attached to the native view hierarchy. To maintain efficiency, you should aim to keep the number of active screens to a minimum (e.g., only the topmost view in a stack or the selected tab).
<ScreenContainer>
<Screen>{tab1}</Screen>
<Screen activityState={2}>{tab2}</Screen>
<Screen>{tab3}</Screen>
</ScreenContainer>To run the application on Android, ensure you have Java 11 active. You can verify your version using javac --version. If necessary, update your JAVA_HOME environment variable or adjust your Android Studio settings.
Once Java 11 is configured, you can launch the app using yarn android or directly from Android Studio.
yarn android