Top Related Projects
A framework for building native applications using React
A complete native navigation solution for React Native
Routing and navigation for your React Native apps
Declarative API exposing platform native touch and gesture system to React Native.
Material Design for React Native (Android & iOS)
UI Components Library for React Native
Quick Overview
React Native Screens is a performance-oriented library for React Native that provides native navigation components. It aims to improve the overall performance and memory usage of React Native apps by utilizing native navigation primitives and reducing the JavaScript-based view hierarchy.
Pros
- Significantly improves performance and reduces memory usage in React Native apps
- Seamlessly integrates with popular navigation libraries like React Navigation
- Provides native implementations for screens, resulting in smoother transitions and animations
- Actively maintained and supported by a large community
Cons
- May require additional setup and configuration compared to standard React Native components
- Some advanced features might not be available on all platforms
- Learning curve for developers unfamiliar with native navigation concepts
- Potential compatibility issues with certain third-party libraries
Code Examples
- Basic screen component:
import { Screen } from 'react-native-screens';
function MyScreen() {
return (
<Screen>
{/* Your screen content */}
</Screen>
);
}
- Stack navigator with native screens:
import { createNativeStackNavigator } from '@react-navigation/native-stack';
import { enableScreens } from 'react-native-screens';
enableScreens();
const Stack = createNativeStackNavigator();
function App() {
return (
<NavigationContainer>
<Stack.Navigator>
<Stack.Screen name="Home" component={HomeScreen} />
<Stack.Screen name="Details" component={DetailsScreen} />
</Stack.Navigator>
</NavigationContainer>
);
}
- Modal presentation:
import { ScreenStack, Screen, ScreenStackHeaderConfig } from 'react-native-screens';
function ModalScreen() {
return (
<ScreenStack>
<Screen>
<ScreenStackHeaderConfig title="Modal" />
{/* Modal content */}
</Screen>
</ScreenStack>
);
}
Getting Started
-
Install the library:
npm install react-native-screens
-
For iOS, install pods:
cd ios && pod install
-
Import and enable screens in your app's entry file:
import { enableScreens } from 'react-native-screens'; enableScreens();
-
Start using
Screen
components in your app or integrate with React Navigation for full native navigation support.
Competitor Comparisons
A framework for building native applications using React
Pros of React Native
- Comprehensive framework for building cross-platform mobile apps
- Large ecosystem with extensive documentation and community support
- Includes built-in components and APIs for various device features
Cons of React Native
- Larger bundle size and potentially slower performance
- More complex setup and configuration process
- May require additional native code for advanced functionality
Code Comparison
React Native (basic component):
import React from 'react';
import { View, Text } from 'react-native';
const MyComponent = () => (
<View>
<Text>Hello, React Native!</Text>
</View>
);
React Native Screens (screen component):
import React from 'react';
import { Screen, Text } from 'react-native-screens';
const MyScreen = () => (
<Screen>
<Text>Hello, React Native Screens!</Text>
</Screen>
);
Key Differences
- React Native Screens focuses on optimizing navigation and screen management
- React Native Screens can improve performance for navigation-heavy apps
- React Native provides a full-featured framework, while React Native Screens is a specialized library
Use Cases
- React Native: Ideal for building complete cross-platform mobile applications
- React Native Screens: Best for enhancing navigation performance in existing React Native apps
A complete native navigation solution for React Native
Pros of react-native-navigation
- More comprehensive navigation solution with built-in features like drawer, tabs, and stack navigation
- Native implementation for better performance and smoother transitions
- Extensive customization options for navigation components
Cons of react-native-navigation
- Steeper learning curve due to its complex API and configuration
- Requires additional setup and linking compared to react-native-screens
- May introduce more dependencies and increase app size
Code Comparison
react-native-navigation:
Navigation.setRoot({
root: {
stack: {
children: [
{ component: { name: 'Home' } }
]
}
}
});
react-native-screens:
import { createNativeStackNavigator } from '@react-navigation/native-stack';
const Stack = createNativeStackNavigator();
<Stack.Navigator>
<Stack.Screen name="Home" component={HomeScreen} />
</Stack.Navigator>
react-native-screens is a lower-level library that provides optimized native navigation primitives, while react-native-navigation offers a more feature-rich, out-of-the-box navigation solution. react-native-screens is often used in conjunction with React Navigation, providing a lightweight and performant foundation for navigation. react-native-navigation, on the other hand, is a standalone solution with its own API and navigation patterns.
Routing and navigation for your React Native apps
Pros of react-navigation
- More comprehensive navigation solution, offering various navigation patterns (stack, tab, drawer)
- Extensive documentation and community support
- Seamless integration with React Native's navigation lifecycle
Cons of react-navigation
- Larger bundle size due to its comprehensive nature
- Steeper learning curve for beginners
- May introduce unnecessary complexity for simple navigation requirements
Code Comparison
react-navigation:
import { NavigationContainer } from '@react-navigation/native';
import { createStackNavigator } from '@react-navigation/stack';
const Stack = createStackNavigator();
function App() {
return (
<NavigationContainer>
<Stack.Navigator>
<Stack.Screen name="Home" component={HomeScreen} />
<Stack.Screen name="Details" component={DetailsScreen} />
</Stack.Navigator>
</NavigationContainer>
);
}
react-native-screens:
import { Screen, ScreenContainer } from 'react-native-screens';
function App() {
return (
<ScreenContainer>
<Screen name="Home" component={HomeScreen} />
<Screen name="Details" component={DetailsScreen} />
</ScreenContainer>
);
}
react-native-screens focuses on optimizing screen management and transitions, while react-navigation provides a full-featured navigation solution. react-native-screens can be used as a performance optimization within react-navigation or other navigation libraries, offering improved memory usage and smoother transitions. The choice between the two depends on the project's specific navigation requirements and performance needs.
Declarative API exposing platform native touch and gesture system to React Native.
Pros of react-native-gesture-handler
- More comprehensive gesture handling capabilities, including complex gestures and multi-touch interactions
- Better performance for gesture-based animations due to native implementation
- Extensive customization options for gesture recognition and response
Cons of react-native-gesture-handler
- Steeper learning curve due to more complex API and concepts
- May introduce unnecessary complexity for simple touch interactions
- Requires additional setup and configuration compared to basic React Native touch handling
Code Comparison
react-native-gesture-handler:
import { PanGestureHandler, State } from 'react-native-gesture-handler';
<PanGestureHandler
onGestureEvent={this._onPanGestureEvent}
onHandlerStateChange={this._onPanHandlerStateChange}>
<Animated.View style={animatedStyles} />
</PanGestureHandler>
react-native-screens:
import { Screen, ScreenContainer } from 'react-native-screens';
<ScreenContainer>
<Screen name="Home" component={HomeScreen} />
<Screen name="Details" component={DetailsScreen} />
</ScreenContainer>
While react-native-gesture-handler focuses on advanced gesture handling, react-native-screens optimizes navigation performance by utilizing native navigation components. The choice between the two depends on the specific needs of your project, with gesture-handler being more suitable for complex touch interactions and screens being better for improving navigation performance.
Material Design for React Native (Android & iOS)
Pros of react-native-paper
- Comprehensive UI component library with Material Design
- Extensive theming capabilities and customization options
- Active community and regular updates
Cons of react-native-paper
- Larger bundle size due to the extensive component library
- May require additional setup for certain components
- Some components might not perfectly match native platform look and feel
Code Comparison
react-native-paper:
import { Button } from 'react-native-paper';
const MyComponent = () => (
<Button mode="contained" onPress={() => console.log('Pressed')}>
Press me
</Button>
);
react-native-screens:
import { Screen } from 'react-native-screens';
const MyScreen = () => (
<Screen>
{/* Screen content */}
</Screen>
);
Key Differences
- react-native-paper focuses on providing a comprehensive UI component library
- react-native-screens optimizes navigation performance and screen management
- react-native-paper is more suitable for rapid UI development with Material Design
- react-native-screens is better for improving overall app performance, especially in navigation
Use Cases
- Use react-native-paper for projects requiring a consistent Material Design look
- Choose react-native-screens for optimizing navigation and screen transitions in complex apps
Community and Support
Both libraries have active communities and regular updates, but react-native-paper generally has more frequent releases and a larger user base due to its broader scope.
UI Components Library for React Native
Pros of react-native-ui-lib
- Comprehensive UI component library with a wide range of pre-built components
- Highly customizable and themeable components
- Includes additional utilities and helpers for common UI tasks
Cons of react-native-ui-lib
- Larger bundle size due to the extensive component library
- Steeper learning curve for developers new to the library
- May require more frequent updates to stay compatible with React Native versions
Code Comparison
react-native-ui-lib:
import { View, Text, Button } from 'react-native-ui-lib';
const MyComponent = () => (
<View>
<Text>Hello, World!</Text>
<Button label="Click me" onPress={() => {}} />
</View>
);
react-native-screens:
import { Screen } from 'react-native-screens';
import { View, Text, Button } from 'react-native';
const MyScreen = () => (
<Screen>
<View>
<Text>Hello, World!</Text>
<Button title="Click me" onPress={() => {}} />
</View>
</Screen>
);
While react-native-ui-lib provides a comprehensive set of UI components, react-native-screens focuses on optimizing navigation and screen management in React Native applications. The choice between the two depends on the specific needs of your project, with react-native-ui-lib being more suitable for projects requiring a rich set of pre-built UI components, and react-native-screens being ideal for improving navigation performance.
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
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;
public class MainActivity extends ReactActivity {
//...code
//react-native-screens override
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(null);
}
public static class MainActivityDelegate extends ReactActivityDelegate {
//...code
}
}
Kotlin
import android.os.Bundle;
class MainActivity: ReactActivity() {
//...code
//react-native-screens override
override fun onCreate(savedInstanceState: Bundle?) {
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.
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
library version | react-native version |
---|---|
3.33.0+ | 0.72.0+ |
3.32.0+ | 0.71.0+ |
3.30.0+ | 0.68.0+ |
3.14.0+ | 0.64.0+ |
3.0.0+ | 0.62.0+ |
2.0.0+ | 0.60.0+ |
Support for Fabric
Fabric is React Native's new rendering system.
Here's a table with summary of supported react-native
versions when Fabric is turned on.
library version | react-native version |
---|---|
3.33.0+ | 0.75.0+ |
3.32.0+ | 0.74.0+ |
3.28.0+ | 0.73.0+ |
3.21.0+ | 0.72.0+ |
3.19.0+ | 0.71.0+ |
3.18.0+ | 0.70.0+ |
3.14.0+ | 0.69.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
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
- for React Navigation v5 to the README in react-native-screens/native-stack
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/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.
Top Related Projects
A framework for building native applications using React
A complete native navigation solution for React Native
Routing and navigation for your React Native apps
Declarative API exposing platform native touch and gesture system to React Native.
Material Design for React Native (Android & iOS)
UI Components Library for React Native
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot