Getting started

The Fundamentals section covers the most important aspects of React Navigation. It should be enough to build a typical mobile application and give you the background to dive deeper into the more advanced topics.

Prior knowledge

If you're already familiar with JavaScript, React and React Native, you'll be able to get moving with React Navigation quickly! If not, we recommend gaining some basic knowledge first, then coming back here when you're done.

1. React Documentation
2. React Native Documentation

Minimum requirements

• react-native >= 0.72.0
• expo >= 52 (if you use Expo Go)
• typescript >= 5.0.0 (if you use TypeScript)

Starter template

You can use the React Navigation template to quickly set up a new project:

npx create-expo-app@latest --template react-navigation/template

This creates a new Expo project with React Navigation already installed and configured. See the project's README.md for more information, then move on to Setting up React Navigation.

Installation

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

In your project directory, run:

npm

npm install @react-navigation/native

yarn

yarn add @react-navigation/native

pnpm

pnpm add @react-navigation/native

bun

bun add @react-navigation/native

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

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

yarn

yarn add react-native-screens react-native-safe-area-context

pnpm

pnpm add react-native-screens react-native-safe-area-context

bun

bun add react-native-screens react-native-safe-area-context

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

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. Supports dynamic screen lists and navigator options.