React Native Screens

Common errors

• Error: `react-native-screens` module not found

  cause 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

  cause 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

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

Warnings

• 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.
• breaking 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.
  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.
• breaking 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.
  Fix: Migrate any usage of the deprecated `native-stack v5` APIs to the current stable or recommended experimental stack APIs before upgrading.
• gotcha 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.
  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.

Install

• npm install react-native-screens npm
• yarn add react-native-screens yarn
• pnpm add react-native-screens pnpm

Imports

• ScreenContainer
  wrong:

  const { ScreenContainer } = require('react-native-screens');

  correct:

  import { ScreenContainer } from 'react-native-screens';

  Used as the root component to manage native screen instances.
• enableScreens
  wrong:

  import enableScreens from 'react-native-screens';

  correct:

  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
  wrong:

  const Screen = require('react-native-screens').Screen;

  correct:

  import { Screen } from 'react-native-screens';

  Represents a single native screen. Typically rendered within a ScreenContainer or a navigator component from a library like React Navigation.

Quickstart

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