{"id":11797,"library":"react-native-screens","title":"React Native Screens","description":"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).","status":"active","version":"4.24.0","language":"javascript","source_language":"en","source_url":"https://github.com/software-mansion/react-native-screens","tags":["javascript","typescript"],"install":[{"cmd":"npm install react-native-screens","lang":"bash","label":"npm"},{"cmd":"yarn add react-native-screens","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-native-screens","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for React Native components.","package":"react","optional":false},{"reason":"Core dependency for any React Native application.","package":"react-native","optional":false}],"imports":[{"note":"Used as the root component to manage native screen instances.","wrong":"const { ScreenContainer } = require('react-native-screens');","symbol":"ScreenContainer","correct":"import { ScreenContainer } from 'react-native-screens';"},{"note":"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.","wrong":"import enableScreens from 'react-native-screens';","symbol":"enableScreens","correct":"import { enableScreens } from 'react-native-screens';"},{"note":"Represents a single native screen. Typically rendered within a ScreenContainer or a navigator component from a library like React Navigation.","wrong":"const Screen = require('react-native-screens').Screen;","symbol":"Screen","correct":"import { Screen } from 'react-native-screens';"}],"quickstart":{"code":"import React, { useState } from 'react';\nimport { Button, View, Text } from 'react-native';\nimport {\n  enableScreens,\n  ScreenContainer,\n  Screen,\n  ScreenStackHeaderConfig,\n} from 'react-native-screens';\n\n// Call enableScreens at the top level of your app to optimize screen rendering.\n// This should be done once, typically in index.js or App.tsx.\nenableScreens();\n\n// Basic screen component demonstration\nfunction MyScreen({ title, color, onNavigate }: { title: string; color: string; onNavigate?: () => void }) {\n  return (\n    <Screen style={{ flex: 1, backgroundColor: color }}>\n      {/* ScreenStackHeaderConfig is often used within Screen to define header properties */}\n      <ScreenStackHeaderConfig\n        title={title}\n        backgroundColor={color === 'white' ? '#f0f0f0' : color}\n        // You can add many more props for header customization\n        // largeTitle={true} // iOS specific\n      />\n      <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>\n        <Text style={{ fontSize: 24, marginBottom: 20 }}>{title}</Text>\n        {onNavigate && (\n          <Button title={`Go to Next`} onPress={onNavigate} />\n        )}\n      </View>\n    </Screen>\n  );\n}\n\n// Main App component to demonstrate ScreenContainer\nexport default function App() {\n  const [activeScreenIndex, setActiveScreenIndex] = useState(0);\n\n  const screens = [\n    <MyScreen key=\"home\" title=\"Home Screen\" color=\"white\" onNavigate={() => setActiveScreenIndex(1)} />,\n    <MyScreen key=\"details\" title=\"Details Screen\" color=\"lightblue\" onNavigate={() => setActiveScreenIndex(0)} />,\n  ];\n\n  return (\n    // ScreenContainer is the root component that manages native screens\n    <ScreenContainer style={{ flex: 1 }}>\n      {screens.map((screen, index) => (\n        // activityState controls whether the screen is active (mounted and visible)\n        // 0: inactive (unmounted/hidden), 1: transitioning, 2: active (visible)\n        <Screen key={screen.key} style={{ flex: 1 }} activityState={index === activeScreenIndex ? 2 : 0}>\n          {screen}\n        </Screen>\n      ))}\n    </ScreenContainer>\n  );\n}","lang":"typescript","description":"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."},"warnings":[{"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.","message":"`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.","severity":"breaking","affected_versions":">=4.25.0"},{"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.","message":"In 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.","severity":"breaking","affected_versions":">=4.16.0"},{"fix":"Migrate any usage of the deprecated `native-stack v5` APIs to the current stable or recommended experimental stack APIs before upgrading.","message":"Version 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.","severity":"breaking","affected_versions":">=4.19.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=4.21.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The native modules are not correctly linked or built into your application.","error":"Error: `react-native-screens` module not found"},{"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).","cause":"The native `RNScreen` component has not been properly registered or linked, typically due to a build issue or incorrect project setup.","error":"Invariant Violation: View config not found for name RNScreen"},{"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.","cause":"`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.","error":"TypeError: (0, _reactNativeScreens.enableScreens) is not a function"}],"ecosystem":"npm"}