Architecting High-Performance Navigation and Interactions in React Native
These five packages form the core infrastructure for building fluid, native-feeling mobile applications with React Native. react-navigation and react-native-navigation provide the routing logic to move between views, while react-native-screens, react-native-gesture-handler, and react-native-reanimated optimize performance by offloading work to native threads. Together, they enable developers to create complex gestures, 60fps animations, and memory-efficient screen stacks that match the quality of fully native apps.
npm下载趋势
GitHub Stars 排名
统计详情
React Native Navigation and Performance Stack: A Technical Deep Dive
Building a production-grade React Native app requires more than just standard components. You need a robust navigation system and performance primitives that bypass the JavaScript bridge for critical interactions. The five packages in this comparison — react-navigation, react-native-navigation, react-native-screens, react-native-gesture-handler, and react-native-reanimated — work together to solve these challenges. Let's examine how they function individually and how they integrate into a cohesive architecture.
🧭 Navigation Architecture: JavaScript vs Native Controllers
The biggest architectural decision is choosing between the two main navigation libraries. They handle screen stacks differently, which impacts how you configure your app.
react-navigation uses a JavaScript-based router that renders components within a single native root view. It is highly customizable and uses a declarative configuration.
// react-navigation: Stack Navigator Configuration
import { createNativeStackNavigator } from '@react-navigation/native-stack';
const Stack = createNativeStackNavigator();
function App() {
return (
<NavigationContainer>
<Stack.Navigator>
<Stack.Screen name="Home" component={HomeScreen} />
<Stack.Screen name="Details" component={DetailsScreen} />
</Stack.Navigator>
</NavigationContainer>
);
}
react-native-navigation bypasses the React root view and pushes native view controllers directly. It requires registering screens globally before use.
// react-native-navigation: Screen Registration & Push
import { Navigation } from 'react-native-navigation';
Navigation.registerComponent('HomeScreen', () => HomeScreen);
Navigation.registerComponent('DetailsScreen', () => DetailsScreen);
Navigation.push('ComponentId', {
component: {
name: 'DetailsScreen',
options: {
topBar: { title: { text: 'Details' } }
}
}
});
📱 Native Screen Optimization: Managing Memory
When dealing with deep navigation stacks, keeping every screen mounted in memory can crash your app. react-native-screens solves this by attaching screens to native containers.
react-native-screens allows you to enable native primitives that detach inactive screens from the window hierarchy.
// react-native-screens: Enabling Native Screens
import { enableScreens } from 'react-native-screens';
enableScreens(); // Call before rendering app
// Usage within a container
import { ScreenContainer, Screen } from 'react-native-screens';
<ScreenContainer>
<Screen active={isActive}>
<HomeScreen />
</Screen>
</ScreenContainer>
react-navigation integrates this automatically when using createNativeStackNavigator, but you must ensure enableScreens() is called at entry.
// react-navigation: Integrating Screens
import { enableScreens } from 'react-native-screens';
enableScreens();
// The Native Stack uses screens internally
const Stack = createNativeStackNavigator();
react-native-navigation handles native controllers inherently, so it does not rely on react-native-screens for its core stack behavior, but you can still use screens for modal presentations within its ecosystem.
// react-native-navigation: Native Stack (Built-in)
// No explicit 'screens' package needed for core push/pop
Navigation.push('ComponentId', { component: { name: 'Screen' } });
👆 Gesture Handling: UI Thread vs JS Thread
Standard React Native touch events travel over the bridge, causing lag. react-native-gesture-handler moves this logic to the UI thread.
react-native-gesture-handler provides native wrappers for touch events. It requires wrapping your app root.
// react-native-gesture-handler: Root Wrapper & Pan Gesture
import { GestureHandlerRootView } from 'react-native-gesture-handler';
import { PanGestureHandler } from 'react-native-gesture-handler';
export default function App() {
return (
<GestureHandlerRootView style={{ flex: 1 }}>
<PanGestureHandler onGestureEvent={onGesture}>
<View style={{ width: 100, height: 100, background: 'red' }} />
</PanGestureHandler>
</GestureHandlerRootView>
);
}
react-navigation depends on this library for swipe gestures in drawers and tabs. Without it, these features fall back to slower JS implementations.
// react-navigation: Drawer Navigation (Requires Gesture Handler)
import { createDrawerNavigator } from '@react-navigation/drawer';
const Drawer = createDrawerNavigator();
// Swipe to open works smoothly only with gesture-handler installed
react-native-navigation also utilizes gesture handler for edge swipes and interactive pop gestures, ensuring consistency with native OS behavior.
// react-native-navigation: Enabling Gestures
Navigation.setDefaultOptions({
sideMenu: {
left: { enabled: true } // Uses native gestures
}
});
🎬 Animation Performance: Worklets and Shared Values
For complex animations, react-native-reanimated allows you to run JavaScript code on the UI thread using worklets.
react-native-reanimated uses useSharedValue and useAnimatedStyle to bypass the bridge entirely during animation frames.
// react-native-reanimated: UI Thread Animation
import { useSharedValue, useAnimatedStyle, withSpring } from 'react-native-reanimated';
function Box() {
const offset = useSharedValue(0);
const style = useAnimatedStyle(() => {
return { transform: [{ translateY: offset.value }] };
});
return <Animated.View style={style} />;
}
react-navigation uses Reanimated internally for its transition animations when configured, ensuring smooth handovers between screens.
// react-navigation: Custom Transition with Reanimated
<Stack.Screen
name="Details"
options={{
transitionSpec: {
open: { animation: 'spring', config: { stiffness: 1000 } }
}
}}
/>
react-native-navigation supports shared element transitions that can be enhanced with Reanimated for custom physics, though it has its own native animation drivers as well.
// react-native-navigation: Shared Element Transition
Navigation.push('ComponentId', {
component: { name: 'Details' },
animations: {
sharedElementTransitions: [/* config */]
}
});
🧩 Putting It All Together: The Standard Stack
For most teams, the recommended architecture combines react-navigation with the performance trio (screens, gesture-handler, reanimated). This offers the best balance of DX and performance.
// Integrated Stack Example
import { GestureHandlerRootView } from 'react-native-gesture-handler';
import { enableScreens } from 'react-native-screens';
import { NavigationContainer } from '@react-navigation/native';
enableScreens();
export default function App() {
return (
<GestureHandlerRootView style={{ flex: 1 }}>
<NavigationContainer>
{/* Navigators go here */}
</NavigationContainer>
</GestureHandlerRootView>
);
}
If you choose react-native-navigation, the setup is slightly different as it manages its own root, but you still wrap content with GestureHandlerRootView for custom gestures.
// Wix Navigation Setup Example
import { Navigation } from 'react-native-navigation';
import { GestureHandlerRootView } from 'react-native-gesture-handler';
Navigation.events().registerAppLaunchedListener(() => {
Navigation.setRoot({
root: {
component: {
name: 'HomeScreen',
options: { topBar: { visible: true } }
}
}
});
});
📊 Summary: Capabilities and Integration
| Feature | react-navigation | react-native-navigation | react-native-screens | react-native-gesture-handler | react-native-reanimated |
|---|---|---|---|---|---|
| Primary Role | JS-based Routing | Native Routing | Native Containers | Native Touch | UI Thread Animations |
| Root View | Single React Root | Multiple Native Views | Wrapper Component | Wrapper Component | Hook-based |
| Dependency | Standalone | Standalone | Infra Dependency | Infra Dependency | Infra Dependency |
| Code Location | JS Config | Global Registry | enableScreens() | GestureHandlerRootView | worklet functions |
| Best For | Flexibility & DX | Pure Native Feel | Memory Optimization | Complex Gestures | 60fps Animations |
💡 Final Recommendation
For 90% of projects, start with react-navigation paired with react-native-screens, react-native-gesture-handler, and react-native-reanimated. This combination gives you the massive community support of React Navigation while ensuring your app feels native through the performance libraries.
Reserve react-native-navigation for cases where you have specific native requirements that the single-root architecture cannot satisfy, or if you are migrating an existing Wix ecosystem app. Regardless of the navigator, always include gesture-handler and reanimated for any app that values polish and responsiveness.
如何选择: react-native-screens vs react-native-reanimated vs react-native-gesture-handler vs react-navigation vs react-native-navigation
- react-native-screens:
Choose
react-native-screensto optimize memory usage and transition performance by leveraging native screen containers likeUINavigationController. It is now a default dependency forreact-navigationnative stacks and should be enabled in almost every production React Native app. It prevents inactive screens from consuming resources while keeping them ready for quick access. - react-native-reanimated:
Choose
react-native-reanimatedwhen you need to run animation logic on the UI thread to guarantee 60fps performance, independent of the JavaScript bridge. It is the go-to library for shared element transitions, complex physics-based animations, and gesture-driven UI changes. Use it whenever standard React Animated API causes frame drops. - react-native-gesture-handler:
Choose
react-native-gesture-handlerwhen your app requires complex touch interactions like swipes, pinch-to-zoom, or draggable elements that must run on the UI thread. It is essential for enabling smooth drawer menus and tab swipes inreact-navigation. Without it, gesture recognition may lag or conflict with the JavaScript thread. - react-navigation:
Choose
react-navigationif you want a community-driven, JavaScript-based routing solution that is highly flexible and easy to configure. It is the standard choice for most React Native projects, offering deep integration withreact-native-screensand a vast ecosystem of plugins. It works best when you need custom navigators or frequent updates to the navigation structure. - react-native-navigation:
Choose
react-native-navigationif you require fully native navigation controllers for maximum performance and a strict native look and feel. Maintained by Wix, it renders native views directly rather than wrapping them in a single React root, which can reduce memory overhead in very large apps. It is ideal for teams comfortable with native iOS/Android concepts and static screen registration.
热门对比
react-native-screens的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.
Fabric
To learn about how to use react-native-screens with Fabric architecture, head over to Fabric README. Instructions on how to run Fabric Example within this repo can be found in the FabricExample README.
Supported platforms
- iOS
- Android
- tvOS
- visionOS
- Windows
- Web
Installation
iOS
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.
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.
Please note that the override code should not be placed inside MainActivityDelegate, but rather directly in MainActivity.
Java
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
}
}
Kotlin
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.
Windows
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.
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
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.
Support for Fabric
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.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+ |
Support for Paper
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+ |
Usage with react-navigation
[!CAUTION] JS API of the native stack has been moved from
react-native-screens/native-stackto@react-navigation/native-stacksince version v6. Currently, native stack v5 (imported fromreact-native-screens/native-stack) is deprecated and will be removed in the upcoming minor release.react-native-screensv4 will support only@react-navigation/native-stackv7.
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.
Experimental support for react-freeze
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.
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 >= v6 to the Native Stack Navigator part of React Navigation documentation
FullWindowOverlay
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
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.
Common problems
Problems with header on iOS
- Focused search bar causes new screens to have incorrect header
- Scrollable content gets cut off by the header with a search bar
- RefreshControl does not work properly with NativeStackNavigator and largeTitle
Solution
Use ScrollView with prop contentInsetAdjustmentBehavior=“automatic” as a main container of the screen and set headerTranslucent: true in screen options.
Other problems
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 has been build and is maintained thanks to the support from Shopify, Expo.io, and Software Mansion.
React Native Screens is created by Software Mansion
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.