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

See the project's README.md for more information on how to get started.

If you created a new project using the template, you can skip the installation steps below and move on to "Hello React Navigation".

Otherwise, you can follow the instructions below to install React Navigation into your existing project.

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.

info

When you use a navigator (such as stack navigator), you'll need to follow that navigator's installation instructions for any additional dependencies.

There are 2 ways to configure navigators:

Static configuration

The static configuration API lets you write your navigation configuration in an object. This reduces boilerplate and simplifies TypeScript types and deep linking. Some aspects can still be changed dynamically.

This is the recommended way to set up your app. If you need more flexibility later, you can mix and match with the dynamic configuration.

Continue to "Hello React Navigation" to start writing some code with the static API.

Dynamic configuration

The dynamic configuration API lets you write your navigation configuration using React components that can change at runtime based on state or props. This offers more flexibility but requires significantly more boilerplate for TypeScript types, deep linking, etc.

Continue to "Hello React Navigation" to start writing some code with the dynamic API.