Registry / web-framework / react-native-screens

react-native-screens

JSON →
library4.24.0jsnpmunverified

react-native-screens is a foundational library for React Native that exposes native screen lifecycle management and view hierarchy optimization directly to JavaScript. It enables navigation libraries, such as React Navigation, to leverage platform-specific navigation primitives for improved performance, smoother transitions, and a more native look and feel. The current stable version is 4.24.0, with minor releases occurring frequently (roughly monthly) as development progresses towards a 5.0 stack implementation. A key differentiator is its focus on utilizing native APIs, which contrasts with purely JavaScript-driven navigation solutions. Notably, version 4.24.0 is the last release tested with React Native's 'legacy architecture'; upcoming versions (from 4.25.0) will drop support for older React Native versions (below 0.82) and the legacy architecture, signaling a shift towards the New Architecture (Fabric).

npm install react-native-screens
INSTALL
IMPORT
SIG · REACT-NATIVE-SCREE
R
react-native-screens
web-frameworkjavascriptv4.24.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

ScreenContainer
import { ScreenContainer } from 'react-native-screens';
const { ScreenContainer } = require('react-native-screens');
Used as the root component to manage native screen instances.
enableScreens
import { enableScreens } from 'react-native-screens';
import enableScreens from 'react-native-screens';
Must be called once at the top level of your app (e.g., App.tsx or index.js) to enable screen optimizations. It is a named export, not a default one.
Screen
import { Screen } from 'react-native-screens';
const Screen = require('react-native-screens').Screen;
Represents a single native screen. Typically rendered within a ScreenContainer or a navigator component from a library like React Navigation.

This example demonstrates how to initialize `react-native-screens` with `enableScreens()`, and use `ScreenContainer` to manage basic `Screen` components with header configurations, simulating screen activation through state changes.

import React, { useState } from 'react'; import { Button, View, Text } from 'react-native'; import { enableScreens, ScreenContainer, Screen, ScreenStackHeaderConfig, } from 'react-native-screens'; // Call enableScreens at the top level of your app to optimize screen rendering. // This should be done once, typically in index.js or App.tsx. enableScreens(); // Basic screen component demonstration function MyScreen({ title, color, onNavigate }: { title: string; color: string; onNavigate?: () => void }) { return ( <Screen style={{ flex: 1, backgroundColor: color }}> {/* ScreenStackHeaderConfig is often used within Screen to define header properties */} <ScreenStackHeaderConfig title={title} backgroundColor={color === 'white' ? '#f0f0f0' : color} // You can add many more props for header customization // largeTitle={true} // iOS specific /> <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}> <Text style={{ fontSize: 24, marginBottom: 20 }}>{title}</Text> {onNavigate && ( <Button title={`Go to Next`} onPress={onNavigate} /> )} </View> </Screen> ); } // Main App component to demonstrate ScreenContainer export default function App() { const [activeScreenIndex, setActiveScreenIndex] = useState(0); const screens = [ <MyScreen key="home" title="Home Screen" color="white" onNavigate={() => setActiveScreenIndex(1)} />, <MyScreen key="details" title="Details Screen" color="lightblue" onNavigate={() => setActiveScreenIndex(0)} />, ]; return ( // ScreenContainer is the root component that manages native screens <ScreenContainer style={{ flex: 1 }}> {screens.map((screen, index) => ( // activityState controls whether the screen is active (mounted and visible) // 0: inactive (unmounted/hidden), 1: transitioning, 2: active (visible) <Screen key={screen.key} style={{ flex: 1 }} activityState={index === activeScreenIndex ? 2 : 0}> {screen} </Screen> ))} </ScreenContainer> ); }
Debug
Known issues
breaking`react-native-screens` v4.25.0 and later will cease support for React Native versions below 0.82 and the 'legacy architecture'. Version 4.24.0 is the last release tested with this setup.
fix
Upgrade your React Native project to version 0.82 or newer and migrate to the New Architecture (Fabric) before updating `react-native-screens` past 4.24.0.
affects: >=4.25.0
breakingIn version 4.16.0, the Android installation steps were significantly altered. Failure to follow the updated instructions can lead to build errors or runtime issues on Android.
fix
Refer to the 'Installation' section of the `react-native-screens` README for the most current Android setup instructions and ensure your project configuration matches.
affects: >=4.16.0
breakingVersion 4.19.0 removed long-deprecated native-stack v5 code from the repository. Projects still relying on this older experimental stack implementation will encounter errors after upgrading.
fix
Migrate any usage of the deprecated `native-stack v5` APIs to the current stable or recommended experimental stack APIs before upgrading.
affects: >=4.19.0
gotchaThe library is actively developing "Stack v5" and other experimental APIs, as noted in recent release logs. These features are subject to change, may contain bugs, and are not recommended for production use without thorough testing.
fix
Avoid experimental APIs in production environments or thoroughly test your application and be prepared for potential breaking changes in minor updates when using these features.
affects: >=4.21.0
Errors
Common errors & fixes
Error: `react-native-screens` module not found
The native modules are not correctly linked or built into your application.
fix
Ensure auto-linking is working (rebuild with `npx react-native run-android`/`ios`). For manual linking issues, check your `Podfile` (iOS) and `build.gradle` (Android) for correct `react-native-screens` entries and clean/rebuild native projects.
Invariant Violation: View config not found for name RNScreen
The native `RNScreen` component has not been properly registered or linked, typically due to a build issue or incorrect project setup.
fix
Verify `react-native-screens` is correctly installed and linked. Clean build caches (`yarn cache clean --force`, `watchman watch-del-all`, `rm -rf node_modules && yarn install`, `cd ios && pod install --repo-update && cd ..`, clean Xcode build folder, clear Metro cache).
TypeError: (0, _reactNativeScreens.enableScreens) is not a function
`enableScreens` is a named export, and this error indicates either a wrong import (e.g., `import enableScreens from 'react-native-screens'`) or a CJS/ESM mismatch.
fix
Ensure `enableScreens` is imported as a named export: `import { enableScreens } from 'react-native-screens';`. For CommonJS, use `const { enableScreens } = require('react-native-screens');`. Confirm `enableScreens()` is called once, early in your app lifecycle.
Upgrade
Version history
4.24.0latest on npm
Audit
Dependencies
reactrequiredPeer dependency for React Native components.
react-nativerequiredCore dependency for any React Native application.
Agent activity
4 hits · last 30 days
node
4
Resources
react-native-screens — npm install react-native-screens · libregistry