Getting started

React Navigation is a navigation library for React Native and Web. It provides routing logic and UI common on mobile apps and PWAs with type-safe navigation, built-in universal links on mobile, and browser history integration on the web.

Installation

The @react-navigation/native package contains the core functionality of React Navigation.

In your project directory, run:

npm

npm install @react-navigation/native@next

yarn

yarn add @react-navigation/native@next

pnpm

pnpm add @react-navigation/native@next

bun

bun add @react-navigation/native@next

Minimum requirements

• react-native >= 0.83
• expo >= 55 (development build is required)
• typescript >= 5.9.2 (if you use TypeScript)
• react-native-web >= 0.21.0 (if you support Web)

Installing dependencies

Next, install the dependencies used by most navigators: react-native-screens and react-native-safe-area-context.

Expo

In your project directory, run:

npx expo install react-native-screens react-native-safe-area-context @callstack/liquid-glass

This will install versions of these libraries that are compatible with your Expo SDK version.

Community CLI

In your project directory, run:

npm

npm install react-native-screens react-native-safe-area-context @callstack/liquid-glass

yarn

yarn add react-native-screens react-native-safe-area-context @callstack/liquid-glass

pnpm

pnpm add react-native-screens react-native-safe-area-context @callstack/liquid-glass

bun

bun add react-native-screens react-native-safe-area-context @callstack/liquid-glass

If you're on a Mac and developing for iOS, install the pods via Cocoapods to complete the linking:

npx pod-install ios

Configuring react-native-screens on Android

react-native-screens requires one additional configuration to properly work on Android.

Edit MainActivity.kt or MainActivity.java under android/app/src/main/java/<your package name>/ and add the highlighted code:

Kotlin

import android.os.Bundle
import com.swmansion.rnscreens.fragment.restoration.RNScreensFragmentFactory

// ...

class MainActivity: ReactActivity() {
  // ...

  override fun onCreate(savedInstanceState: Bundle?) {
    supportFragmentManager.fragmentFactory = RNScreensFragmentFactory()
    super.onCreate(savedInstanceState)
  }

  // ...
}

Java

import android.os.Bundle;
import com.swmansion.rnscreens.fragment.restoration.RNScreensFragmentFactory;

// ...

public class MainActivity extends ReactActivity {
  // ...

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    getSupportFragmentManager().setFragmentFactory(new RNScreensFragmentFactory());
    super.onCreate(savedInstanceState);
  }

  // ...
}

This avoids crashes related to View state not being persisted across Activity restarts.

Opting-out of predictive back on Android

React Navigation doesn't yet support Android's predictive back gesture, so you need to disable it for the system back gesture to work properly.

In AndroidManifest.xml, set android:enableOnBackInvokedCallback to false in the <application> tag (or <activity> tag to opt-out at activity level):

<application
  android:enableOnBackInvokedCallback="false"
  >
  <!-- ... -->
</application>

Setting up React Navigation

The guides linked below cover the fundamentals of React Navigation, and give you the background to dive deeper into the more advanced topics.

When using React Navigation, you configure navigators in your app. Navigators handle transitions between screens and provide UI such as headers, tab bars, etc.

There are 2 ways to configure navigators:

• Static configuration Recommended

  Object-based configuration with automatic TypeScript types and deep linking. Supports static screen lists with dynamic navigator options.

• Dynamic configuration

  Component-based configuration with significantly more boilerplate for TypeScript and deep linking. Supports dynamic screen lists and navigator options.