Native Navigation: Airbnb's React Native Library for Platform Navigation

What Native Navigation Solves and Who It Is For

React Native applications typically navigate between screens in one of two ways: through JavaScript-based navigation libraries that build stacks and tabs using animated React Native components, or through libraries that delegate to iOS and Android platform navigation components. Native Navigation belongs to the second category.

The practical difference is that platform-native navigation uses the same UINavigationController on iOS and the same back-stack mechanisms on Android that any native app uses. The README states: "Native Navigation is unique in that it is built on top of the iOS and Android platform navigational components, and is thus more 'native' than most other options which implement navigation from scratch in JavaScript."

This project is aimed at React Native developers who want that level of platform fidelity and are willing to work with a library that is still in beta. The README is direct about this constraint: many core APIs are subject to change, and the project is not considered production-ready until it reaches version 1.0.

Architecture: Navigation Components Live in Native Code

Unlike JavaScript-based React Native navigation where a navigator is a React component that manages a state machine and renders screens through Animated, Native Navigation delegates navigation state to iOS and Android platform code. The project is written primarily in Java (for Android) with corresponding iOS code.

Screens are registered with the Navigator, and navigation operations such as pushing, presenting, popping, and dismissing are called through the Navigator API. This means the navigation stack is owned by the platform, not by a JavaScript state machine. The platform handles gestures, transitions, and back-button behavior using the native patterns a user already knows from other apps on their device.

The API surface listed in the README covers Navigator.registerScreen, Navigator.push, Navigator.present, Navigator.pop, Navigator.dismiss, a Config type for navigator-level configuration, Spacer, Tab, TabBar, SharedElement, and SharedElementGroup. Deep linking and custom navigation implementations are documented in separate guides under docs/guides/.

Running the Example Project

To see Native Navigation working, clone the repository and run the example app. Both npm and the Ruby bundler gem are required.

git clone https://github.com/airbnb/native-navigation.git
cd native-navigation

Install JavaScript dependencies:

npm install

Start the Metro bundler:

npm start

From a second terminal, run on iOS or Android:

npm run run:ios
npm run run:android

The installation guide for adding Native Navigation to an existing app lives at docs/installation.md rather than in the README itself. The README points there and to the basic usage guide at docs/guides/basic-usage.md. The example project directory contains screens, components, and platform-specific folders for iOS and Android.

Shared Element Transitions and Other Documented Features

The guide list in the README documents capabilities beyond basic push and pop navigation. The shared element transitions guide, referenced at docs/guides/shared-element-transitions.md, covers the SharedElement and SharedElementGroup API types. Shared element transitions animate a UI element from one screen to another during a navigation event, which requires coordination between the outgoing and incoming screens.

The tabs guide covers tab-based navigation using the Tab and TabBar types. The deep linking guide documents how to wire up URL-based navigation. Platform differences between iOS and Android are documented in a separate guide, which reflects that underlying platform navigation components behave differently on each OS and that Native Navigation exposes those differences rather than abstracting them away.

The project structure guide at docs/guides/project-structure.md documents how the repository is organized across its JavaScript, iOS, and Android layers. The glossary at GLOSSARY.md defines the terminology the project uses.

Why the README Warns Against Production Use

The README opens with a disclaimer in bold: "This project is currently in beta. Many of the core APIs are subject to change, and we do not consider this project 'Production Ready' until it hits a 1.0 release."

At version 0.2.2, the package is distributed on npm under the name native-navigation. The last push to the repository was on 2025-11-06. A project that carries a beta label from its own authors and has not received a push in close to a year presents real adoption risk. The core API may change in ways that break existing code between any two updates.

For teams evaluating it, the missing pieces are the administration experience (there is no admin panel), authentication integration, mailers, and analytics, all of which the README notes are left to the adopter. The package.json test script returns an error and exits, meaning there is no automated test suite in the repository.

Native Navigation versus React Native Navigation by Wix

The README names React Native Navigation by Wix as the primary alternative and recommends it directly: "If you need a stable / production-ready navigation library today that uses native platform based navigation components, we recommend you check this library out."

Both libraries share the architectural decision to use platform navigation components instead of JavaScript-based animations. React Native Navigation by Wix has been available longer than Native Navigation. The README also mentions React Navigation as an alternative for teams that are comfortable with JavaScript-based navigation solutions.

React Navigation takes a different architectural approach: it implements navigation as React components using JavaScript and does not depend on platform navigation components. This makes it easier to share navigation behavior across platforms and to reason about navigation state as React state, at the cost of not using the platform's native navigation patterns. The choice between these libraries largely comes down to whether platform-native navigation fidelity or JavaScript-based predictability matters more to a team.

Editorial conclusion

Native Navigation suits React Native developers who want to study or contribute to a navigation library built directly on iOS and Android platform components rather than JavaScript-based solutions. The README makes its own position clear: it is not production-ready and recommends React Native Navigation by Wix for teams that need stable native platform navigation today. The last push to the repository was on 2025-11-06. The project is at version 0.2.2, licensed under MIT, and the roadmap document at docs/roadmap.md describes what is needed to reach 1.0.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository