• Stars
    star
    3,039
  • Rank 14,841 (Top 0.3 %)
  • Language
    TypeScript
  • License
    MIT License
  • Created over 6 years ago
  • Updated about 1 month ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Native navigation primitives for your React Native app.

React Native Screens by Software Mansion

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
  • 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.

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
    }
}

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

version react-native version
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.

  • As of version 3.19.0 of this project, Fabric is supported only for react-native 0.71+. Support for lower versions has been dropped.
  • As of version 3.18.0 of this project, Fabric is supported only for react-native 0.70+. Support for lower versions has been dropped.
  • As of version 3.14.0 of this project, Fabric is supported only for react-native 0.69+. Support for lower versions has been dropped.
version react-native version
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
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.64 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:

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/TestsExample/src/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

Solution

Use ScrollView with prop contentInsetAdjustmentBehavior=β€œautomatic” as a main container of the screen and set headerTranslucent: true in screen options.

Other problems

Problem Solution
SVG component becomes transparent when goBack related PRs
Memory leak while moving from one screen to another in the same stack explanation
LargeHeader stays small after pop/goBack/swipe gesture on iOS 14+ potential fix
onScroll and onMomentumScrollEnd of previous screen triggered in bottom tabs explanation

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.

shopify expo swm

More Repositories

1

react-native-reanimated

React Native's Animated library reimplemented
TypeScript
8,941
star
2

react-native-svg

SVG library for React Native, React Native Web, and plain React web projects.
Java
7,475
star
3

react-native-gesture-handler

Declarative API exposing platform native touch and gesture system to React Native.
TypeScript
6,090
star
4

react-freeze

Prevent React component subtrees from rendering.
TypeScript
1,539
star
5

radon-ide

VSCode extension that turns your editor into a fully fledged IDE for React Native and Expo.
JavaScript
947
star
6

starknet.py

✨ 🐍 Python SDK for Starknet.
Python
259
star
7

protostar

Protostar is a toolchain for developing and testing Starknet contracts
Python
247
star
8

scarb

The Cairo package manager
Rust
178
star
9

live-compositor

Media server for real-time, low latency, programmable video and audio mixing.
Rust
146
star
10

TypeGPU

TypeScript library that enhances the WebGPU API, allowing resource management in a type-safe, declarative way.
TypeScript
124
star
11

setup-ci

CLI to spin your CI/CD for react-native!
TypeScript
119
star
12

starknet-jvm

Starknet SDK for JVM languages (Java, Kotlin, Scala)
Kotlin
63
star
13

state-of-react-native

Repository for collaborating on the shape of the State of React Native surveys.
62
star
14

starknet.swift

Starknet SDK for Swift language
Swift
24
star
15

cairo-profiler

Profiler for Cairo programming language & Starknet
Rust
24
star
16

setup-scarb

Sets up Scarb in your GitHub Actions workflow.
JavaScript
19
star
17

docker-janus-gateway

Docker image of the Janus Gateway
Dockerfile
18
star
18

universal-sierra-compiler

Rust
15
star
19

asdf-scarb

Scarb plugin for the asdf version manager
Shell
7
star
20

cairo-coverage

Code coverage tool for cairo
Rust
6
star
21

scarb-nightlies

This repository stores nightly builds of Scarb, go to Releases to obtain them
3
star
22

software-mansion.github.io

2
star