Getting started

What follows within the Fundamentals section of this documentation is a tour of the most important aspects of React Navigation. It should cover enough for you to know how to build your typical small mobile application, and give you the background that you need to dive deeper into the more advanced parts of React Navigation.

Pre-requisites

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

Here are some resources to help you out:

1. Main Concepts of React
2. Getting started with React Native
3. React Hooks
4. React Context

Minimum requirements

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

Starter template

If you're starting a new project, you can use the React Navigation template to quickly set up a new project with Static configuration:

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

Installing dependencies

Let's also install and configure dependencies used by most navigators. The libraries we will install now are 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

If you're on a Mac and developing for iOS, you need to 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 file under android/app/src/main/java/<your package name>/, and add the highlighted code to the body of MainActivity class:

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 change is required to avoid crashes related to View state being not persisted consistently across Activity restarts.

Opting-out of predictive back on Android

React Navigation doesn't yet support Android's predictive back gesture. Disabling it is necessary for the system back gesture to work properly with React Navigation.

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

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

Setting up React Navigation

Once you've installed and configured the dependencies, you can move on to setting up your project to use React Navigation.

When using React Navigation, you configure navigators in your app. Navigators handle the transition between screens in your app and provide UI such as header, tab bar etc.

info

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

There are 2 primary ways to configure the navigators:

Static configuration

The static configuration API lets you write your configuration in an object, and is defined statically, though some aspects of the configuration can still can be changed dynamically. This has reduced boilerplate and simplifies things such as TypeScript types and deep linking.

If you're starting a new project or are new to React Navigation, this is the recommended way to set up your app. If you need more flexibility in the future, you can always 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 configuration in React components, and can change at runtime based on state or props. This allows for more flexibility but requires significantly more boilerplate and configuration for Typescript types, deep linking etc.

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