react-native-screens

react-native-screens exposes the platform’s native navigation container primitives to React Native, so each screen in your app is backed by a real native view (UIViewController on iOS, Fragment on Android) instead of a plain JavaScript-managed View. This lets the operating system take over view lifecycle, memory management, and transition animations, delivering smoother navigation and lower memory usage.

It is not a standalone navigation library but the low-level foundation that popular libraries like react-navigation and Expo build on. Once installed, screen optimizations are enabled automatically, and advanced components such as native stacks, search bars, and full-window overlays become available across iOS, Android, tvOS, visionOS, Windows, and Web.

What You Get

• Native-backed screen components (Screen, ScreenStack, ScreenContainer) that replace JavaScript-managed Views with real native containers
• A native stack implementation with platform-standard headers, back gestures, and transition animations
• Extra native building blocks such as SearchBar, FullWindowOverlay, and form-sheet/modal presentation
• Automatic memory optimization that detaches off-screen views via react-freeze
• Broad platform coverage: iOS, Android, tvOS, visionOS, Windows, and Web

Common Use Cases

• Powering react-navigation or Expo Router so stack, tab, and drawer navigators use native screens
• Adopting a native stack navigator for platform-authentic push/pop transitions and headers
• Reducing memory footprint in apps with deep navigation trees by freezing off-screen screens
• Adding native iOS search bars or full-window overlays to navigation headers

Under The Hood

Architecture

The library is a thin TypeScript surface (src/index.tsx re-exporting components from src/components/) sitting on top of a substantial native implementation. Each JS component like Screen.tsx or ScreenStack.tsx renders a codegen-generated Fabric native component; src/fabric/NativeScreensModule is imported for its side effect of registering the TurboModule. On the native side, iOS is written in Objective-C++/Swift under ios/ (e.g. RNSScreenView, RNSScreenStackView), Android in Kotlin under android/src/main/java/com/swmansion/rnscreens (Fragment-based screen restoration, custom toolbars, bottom sheets), and shared logic in C++ under cpp/. The codegenConfig in package.json declares dozens of native component specs that React Native’s codegen turns into the Fabric bindings the JS layer talks to.

Tech Stack

Written in TypeScript with only two runtime JS dependencies — react-freeze (to unmount off-screen subtrees) and warn-once. React and react-native are peer dependencies. Native code spans Kotlin, Swift/Objective-C++, and C++, built through the React Native Fabric renderer and codegen pipeline, with a CocoaPods podspec (RNScreens.podspec) and Gradle for distribution. Tooling includes Jest, ESLint, Prettier, clang-format, swift-format, and Husky git hooks.

Code Quality

The codebase is fully typed and platform-aware, with dedicated .web.tsx, .windows.tsx, and native variants per component signalling careful cross-platform separation. Linting and formatting are enforced across every language layer (JS, Android, Swift, C++) via separate scripts and Husky pre-commit hooks, and an AGENTS.md/CLAUDE.md documents contributor conventions. A test:unit Jest script exists, though automated coverage is light relative to the native surface — most verification happens through the extensive example apps (apps/, FabricExample/, TVOSExample/) rather than unit tests.

API Design

The public API is intentionally low-level, exporting native primitives (Screen, ScreenStack, ScreenContainer, SearchBar, FullWindowOverlay) plus toggles like enableScreens and enableFreeze. Most app developers never touch it directly — it is consumed transitively through react-navigation — so ergonomics favor library authors. For direct users, installation is largely automatic via auto-linking, though Android requires a documented MainActivity override to avoid state-restoration crashes, and the fast-moving version-to-react-native compatibility matrix demands attention.