# React Navigation 4.x Documentation

## Getting started

Source: https://reactnavigation.org/docs/4.x/getting-started

React Navigation is born from the React Native community's need for an extensible yet easy-to-use navigation solution written entirely in JavaScript (so you can read and understand all of the source), on top of powerful native primitives.

Before you commit to using React Navigation for your project, you might want to read the [anti-pitch](pitch.md) — it will help you to understand the tradeoffs that we have chosen along with the areas where we consider the library to be deficient currently.

## What to expect

If you're already familiar with React Native then you'll be able to get moving with React Navigation quickly! If not, you may want to read sections 1 to 4 (inclusive) of [React Native Express](http://reactnativeexpress.com/) first, then come back here when you're done.

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.

## Start from a template

The easiest way to get running with `react-navigation` is to initialize a project using `expo-cli`. You can install this with `npm i -g expo-cli`.

- If you'd like to create a [managed React Native project](https://docs.expo.io/versions/latest/introduction/managed-vs-bare) then choose the `blank` template under the Managed workflow heading.
- If you'd like a [bare React Native project](https://docs.expo.io/versions/latest/introduction/managed-vs-bare/#bare-workflow), then choose `minimal` under the Bare workflow heading.
- In both cases you can pick the TypeScript version of the template if you prefer — React Navigation ships with TypeScript types.

Once the project is initialized, in the project directory run `npx expo install react-navigation react-native-gesture-handler react-native-reanimated react-native-screens`, and you're ready to go! You can now continue to ["Hello React Navigation"](hello-react-navigation.md) to start writing some code.

## Install into an existing project

Install the `react-navigation` package in your React Native project.

```bash npm2yarn
npm install react-navigation
```

React Navigation is made up of some core utilities and those are then used by navigators to create the navigation structure in your app. Don't worry too much about this for now, it'll become clear soon enough! To frontload the installation work, let's also install and configure dependencies used by most navigators, then we can move forward with starting to write some code.

The libraries we will install now are [`react-native-gesture-handler`](https://github.com/software-mansion/react-native-gesture-handler), [`react-native-reanimated`](https://github.com/software-mansion/react-native-reanimated), [`react-native-screens`](https://github.com/software-mansion/react-native-screens) and [`react-native-safe-area-context`](https://github.com/th3rdwave/react-native-safe-area-context). If you already have these libraries installed and at the latest version, you are done here! Otherwise, read on.

#### Installing dependencies into an Expo managed project

In your project directory, run:

```bash
npx expo install react-native-gesture-handler react-native-reanimated react-native-screens react-native-safe-area-context @react-native-community/masked-view
```

This will install versions of these libraries that are compatible.

You can now continue to ["Hello React Navigation"](hello-react-navigation.md) to start writing some code.

#### Installing dependencies into a bare React Native project

In your project directory, run:

```bash npm2yarn
npm install react-native-reanimated react-native-gesture-handler react-native-screens react-native-safe-area-context @react-native-community/masked-view
```

> Note: You might get warnings related to peer dependencies after installation. They are usually caused by incorrect version ranges specified in some packages. You can safely ignore most warnings as long as your app builds.

Next, we need to link these libraries. The steps depends on your React Native version:

- **React Native 0.60 and higher**

  On newer versions of React Native, [linking is automatic](https://github.com/react-native-community/cli/blob/master/docs/autolinking.md).

  If you're on a Mac and developing for iOS, you need to install pods to complete the linking. Make sure you have [Cocoapods](https://cocoapods.org/) installed. Then run:

  ```bash
  cd ios; pod install; cd ..
  ```

- **React Native 0.59 and lower**

  If you're on an older React Native version, you need to manually link the dependencies. To do that, run:

  ```bash
  react-native link react-native-reanimated
  react-native link react-native-gesture-handler
  react-native link react-native-screens
  react-native link react-native-safe-area-context
  ```

  You also need to configure [jetifier](https://github.com/mikehardy/jetifier) to support dependencies using `androidx`:

  ```bash npm2yarn
  npm install --save-dev jetifier
  ```

  Then add it to the `postinstall` script in `package.json`:

  ```json
  "scripts": {
    "postinstall": "jetifier -r"
  }
  ```

  > Note: Remember to remove this when you upgrade to React Native 0.60 and higher.

  Now, run the `postinstall` script manually:

  ```bash
  npm run postinstall
  ```

To finalize installation of `react-native-gesture-handler` for Android, make the following modifications to `MainActivity.java`:

```diff
package com.reactnavigation.example;

import com.facebook.react.ReactActivity;
+ import com.facebook.react.ReactActivityDelegate;
+ import com.facebook.react.ReactRootView;
+ import com.swmansion.gesturehandler.react.RNGestureHandlerEnabledRootView;

public class MainActivity extends ReactActivity {

  @Override
  protected String getMainComponentName() {
    return "Example";
  }

+  @Override
+  protected ReactActivityDelegate createReactActivityDelegate() {
+    return new ReactActivityDelegate(this, getMainComponentName()) {
+      @Override
+      protected ReactRootView createRootView() {
+        return new RNGestureHandlerEnabledRootView(MainActivity.this);
+      }
+    };
+  }
}
```

Then add the following at the top of your entry file, such as `index.js` or `App.js`:

```js
import 'react-native-gesture-handler';
```

> Note: When you use a navigator (such as stack navigator), you'll need to follow the installation instructions of that navigator for any additional dependencies. If you're getting an error "Unable to resolve module", you need to install that module in your project.

Now you are ready to build and run your app on the device/simulator.

Continue to ["Hello React Navigation"](hello-react-navigation.md) to start writing some code.

---

## Hello React Navigation

Source: https://reactnavigation.org/docs/4.x/hello-react-navigation

In a web browser, you can link to different pages using an anchor (`<a>`) tag. When the user clicks on a link, the URL is pushed to the browser history stack. When the user presses the back button, the browser pops the item from the top of the history stack, so the active page is now the previously visited page. React Native doesn't have a built-in idea of a global history stack like a web browser does -- this is where React Navigation enters the story.

React Navigation's stack navigator provides a way for your app to transition between screens and manage navigation history. If your app uses only one stack navigator then it is conceptually similar to how a web browser handles navigation state - your app pushes and pops items from the navigation stack as users interact with it, and this results in the user seeing different screens. A key difference between how this works in a web browser and in React Navigation is that React Navigation's stack navigator provides the gestures and animations that you would expect on Android and iOS when navigating between routes in the stack.

Lets start by demonstrating the most common navigator, `createStackNavigator`.

Before continuing, first install [`react-navigation-stack`](https://github.com/react-navigation/react-navigation/tree/4.x/packages/stack):

```bash npm2yarn
npm install react-navigation-stack @react-native-community/masked-view react-native-safe-area-context
```

## Creating a stack navigator

`createStackNavigator` is a function that returns a React component. It takes _a route configuration object_ and, optionally, _an options object_ (we omit this below, for now). `createAppContainer` is a function that returns a React component to take as a parameter the React component created by the `createStackNavigator`, and can be directly exported from `App.js` to be used as our App's root component.

<samp id="hello-react-navigation">Hello World</samp>

```js
import React from 'react';
import { View, Text } from 'react-native';
import { createAppContainer } from 'react-navigation';
import { createStackNavigator } from 'react-navigation-stack';

class HomeScreen extends React.Component {
  render() {
    return (
      <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
        <Text>Home Screen</Text>
      </View>
    );
  }
}

const AppNavigator = createStackNavigator({
  Home: {
    screen: HomeScreen,
  },
});

export default createAppContainer(AppNavigator);
```

If you run this code, you will see a screen with an empty navigation bar and a grey content area containing your `HomeScreen` component. The styles you see for the navigation bar and the content area are the default configuration for a stack navigator, we'll learn how to configure those later.

> The casing of the route name doesn't matter -- you can use lowercase `home` or capitalized `Home`, it's up to you. We prefer capitalizing our route names.

> The only required configuration for a route is the `screen` component. You can read more about the other options available in the [StackNavigator reference](stack-navigator.md).

In React Native, the component exported from `App.js` is the entry point (or root component) for your app -- it is the component from which every other component descends. It's often useful to have more control over the component at the root of your app than you would get from exporting the result of `createAppContainer`, so let's export a component that just renders our `AppNavigator` stack navigator.

```js
const AppContainer = createAppContainer(AppNavigator);

export default class App extends React.Component {
  render() {
    return <AppContainer />;
  }
}
```

## Route configuration shorthand

Given that the only route configuration we have for `Home` is the screen component, we don't need to use the `{ screen: HomeScreen }` configuration format, we can use the screen component directly.

```js
const AppNavigator = createStackNavigator({
  Home: HomeScreen,
});
```

## Adding a second route

The `<AppContainer />` component doesn't accept any props -- all configuration is specified in the `options` parameter to the `AppNavigator` `createStackNavigator` function. We left the `options` blank, so it just uses the default configuration. To see an example of using the `options` object, we will add a second screen to the stack navigator.

<samp id="hello-react-navigation-full" />

```js
// Other code for HomeScreen here...

class DetailsScreen extends React.Component {
  render() {
    return (
      <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
        <Text>Details Screen</Text>
      </View>
    );
  }
}

const AppNavigator = createStackNavigator(
  {
    Home: HomeScreen,
    Details: DetailsScreen,
  },
  {
    initialRouteName: 'Home',
  }
);

// Other code for App component here...
```

Now our stack has two _routes_, a `Home` route and a `Details` route. The `Home` route corresponds to the `HomeScreen` component, and the `Details` route corresponds to the `DetailsScreen` component. The initial route for the stack is the `Home` route. The natural question at this point is: "how do I go from the Home route to the Details route?". That is covered in the next section.

## Summary

- React Native doesn't have a built-in API for navigation like a web browser does. React Navigation provides this for you, along with the iOS and Android gestures and animations to transition between screens.
- `createStackNavigator` is a function that takes a route configuration object and an options object and returns a React component.
- The keys in the route configuration object are the route names and the values are the configuration for that route. The only required property on the configuration is the `screen` (the component to use for the route).
- To specify what the initial route in a stack is, provide an `initialRouteName` on the stack options object.

---

## Moving between screens

Source: https://reactnavigation.org/docs/4.x/navigating

In the previous section, ["Hello React Navigation"](hello-react-navigation.md), we defined a stack navigator with two routes (`Home` and `Details`), but we didn't learn how to let a user navigate from `Home` to `Details` (although we did learn how to change the _initial_ route in our code, but forcing our users to clone our repository and change the route in our code in order to see another screen is arguably among the worst user experiences one could imagine).

If this was a web browser, we'd be able to write something like this:

```
<a href="details.html">Go to Details</a>
```

Another way to write this would be:

```
<a onClick={() => { document.location.href = "details.html"; }}>Go to Details</a>
```

We'll do something similar to the latter, but rather than using a `document` global we'll use the `navigation` prop that is passed down to our screen components.

## Navigating to a new screen

<samp id="new-screen">First navigation</samp>

```js
import * as React from 'react';
import { Button, View, Text } from 'react-native';
import { createAppContainer } from 'react-navigation';
import { createStackNavigator } from 'react-navigation-stack';

class HomeScreen extends React.Component {
  render() {
    return (
      <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
        <Text>Home Screen</Text>
        <Button
          title="Go to Details"
          onPress={() => this.props.navigation.navigate('Details')}
        />
      </View>
    );
  }
}

// ... other code from the previous section
```

Let's break this down:

- `this.props.navigation`: the `navigation` prop is passed in to every **screen component** ([definition](glossary-of-terms.md#screen-component)) in stack navigator (more about this later in ["The navigation prop in depth"](navigation-prop.md)).
- `navigate('Details')`: we call the `navigate` function (on the `navigation` prop &mdash; naming is hard!) with the name of the route that we'd like to move the user to.

> If we call `this.props.navigation.navigate` with a route name that we haven't defined on a stack navigator, nothing will happen. Said another way, we can only navigate to routes that have been defined on our stack navigator &mdash; we cannot navigate to an arbitrary component.

So we now have a stack with two routes: 1) the Home route 2) the Details route. What would happen if we navigated to the Details route again, from the Details screen?

## Navigate to a route multiple times

<samp id="multiple-navigate" />

```js
class DetailsScreen extends React.Component {
  render() {
    return (
      <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
        <Text>Details Screen</Text>
        <Button
          title="Go to Details... again"
          onPress={() => this.props.navigation.navigate('Details')}
        />
      </View>
    );
  }
}
```

If you run this code, you'll notice that when you tap "Go to Details... again" that it doesn't do anything! This is because we are already on the Details route. The `navigate` function roughly means "go to this screen", and if you are already on that screen then it makes sense that it would do nothing.

Let's suppose that we actually _want_ to add another details screen. This is pretty common in cases where you pass in some unique data to each route (more on that later when we talk about `params`!). To do this, we can change `navigate` to `push`. This allows us to express the intent to add another route regardless of the existing navigation history.

<samp id="multiple-push">push</samp>

```js
<Button
  title="Go to Details... again"
  onPress={() => this.props.navigation.push('Details')}
/>
```

Each time you call `push` we add a new route to the navigation stack. When you call `navigate` it first tries to find an existing route with that name, and only pushes a new route if there isn't yet one on the stack.

## Going back

The header provided by stack navigator will automatically include a back button when it is possible to go back from the active screen (if there is only one screen in the navigation stack, there is nothing that you can go back to, and so there is no back button).

Sometimes you'll want to be able to programmatically trigger this behavior, and for that you can use `this.props.navigation.goBack();`.

<samp id="go-back">goBack</samp>

```js
class DetailsScreen extends React.Component {
  render() {
    return (
      <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
        <Text>Details Screen</Text>
        <Button
          title="Go to Details... again"
          onPress={() => this.props.navigation.push('Details')}
        />
        <Button
          title="Go to Home"
          onPress={() => this.props.navigation.navigate('Home')}
        />
        <Button
          title="Go back"
          onPress={() => this.props.navigation.goBack()}
        />
      </View>
    );
  }
}
```

> On Android, React Navigation hooks in to the hardware back button and fires the `goBack()` function for you when the user presses it, so it behaves as the user would expect.

Another common requirement is to be able to go back _multiple_ screens -- for example, if you are several screens deep in a stack and want to dismiss all of them to go back to the first screen. In this case, we know that we want to go back to `Home` so we can use `navigate('Home')` (not `push`! try that out and see the difference). Another alternative would be `navigation.popToTop()`, which goes back to the first screen in the stack.

## Summary

- `this.props.navigation.navigate('RouteName')` pushes a new route to the stack navigator if it's not already in the stack, otherwise it jumps to that screen.
- We can call `this.props.navigation.push('RouteName')` as many times as we like and it will continue pushing routes.
- The header bar will automatically show a back button, but you can programmatically go back by calling `this.props.navigation.goBack()`. On Android, the hardware back button just works as expected.
- You can go back to an existing screen in the stack with `this.props.navigation.navigate('RouteName')`, and you can go back to the first screen in the stack with `this.props.navigation.popToTop()`.
- The `navigation` prop is available to all screen components (components defined as screens in route configuration and rendered by React Navigation as a route).

---

## Navigation lifecycle

Source: https://reactnavigation.org/docs/4.x/navigation-lifecycle

In the previous section, we worked with a stack navigator that has two screens (`Home` and `Details`) and learned how to use `this.props.navigation.navigate('RouteName')` to navigate between the routes.

An important question in this context is: what happens with `Home` when we navigate away from it, or when we come back to it? How does a route find out that a user is leaving it or coming back to it?

Coming to React Navigation from the web, you may assume that when user navigates from route `A` to route `B`, `A` will unmount and its `componentWillUnmount` will be called. You may also expect `A` will remount again when user comes back to it. While these React lifecycle methods are still valid and are used in React Navigation, their usage differs from the web. This is driven by more complex needs of mobile navigation.

## Example scenario

Consider a stack navigator with screens `A` and `B`. After navigating to `A`, its `componentDidMount` is called. When pushing `B`, its `componentDidMount` is also called, but `A` remains mounted on the stack and its `componentWillUnmount` is therefore not called.

When going back from `B` to `A`, `componentWillUnmount` of `B` is called, but `componentDidMount` of `A` is not because `A` remained mounted the whole time.

## Subscribing to lifecycle events

Now that we understand how React lifecycle methods work in React Navigation, let's answer the question we asked at the beginning: "How do we find out that a user is leaving it or coming back to it?"

React Navigation emits events to screen components that subscribe to them. There are four different events that you can subscribe to: `willFocus`, `willBlur`, `didFocus` and `didBlur`. Read more about them in the [API reference](navigation-prop.md#addlistener---subscribe-to-updates-to-navigation-lifecycle).

Many of your use cases may be covered with the [`withNavigationFocus` higher-order-component](with-navigation-focus.md), the [`<NavigationEvents />` component](navigation-events.md), or the [useFocusState hook](https://github.com/react-navigation/hooks#usefocusstate).

## Summary

- While Reacts lifecycle methods are still valid, React Navigation adds more lifecycle events that you can subscribe to through the `navigation` prop.
- You may also use the `withNavigationFocus` HOC or `<NavigationEvents />` component to react to lifecycle changes.

---

## Passing parameters to routes

Source: https://reactnavigation.org/docs/4.x/params

Remember when I said "more on that later when we talk about `params`!"? Well, the time has come.

Now that we know how to [create a stack navigator with some routes](hello-react-navigation.md) and [navigate between those routes](navigating.md), let's look at how we can pass data to routes when we navigate to them.

There are two pieces to this:

1. Pass params to a route by putting them in an object as a second parameter to the `navigation.navigate` function: `this.props.navigation.navigate('RouteName', { /* params go here */ })`

2. Read the params in your screen component: `this.props.navigation.getParam(paramName, defaultValue)`.

> We recommend that the params you pass are JSON-serializable. That way, you'll be able to use [state persistence](state-persistence.md) and your screen components will have the right contract for implementing [deep linking](deep-linking.md).

<samp id="passing-params" />

```js
class HomeScreen extends React.Component {
  render() {
    return (
      <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
        <Text>Home Screen</Text>
        <Button
          title="Go to Details"
          onPress={() => {
            this.props.navigation.navigate('Details', {
              itemId: 86,
              otherParam: 'anything you want here',
            });
          }}
        />
      </View>
    );
  }
}

class DetailsScreen extends React.Component {
  render() {
    const { navigation } = this.props;
    return (
      <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
        <Text>Details Screen</Text>
        <Text>
          itemId: {JSON.stringify(navigation.getParam('itemId', 'NO-ID'))}
        </Text>
        <Text>
          otherParam:
          {JSON.stringify(navigation.getParam('otherParam', 'default value'))}
        </Text>
        <Button
          title="Go to Details... again"
          onPress={() =>
            navigation.push('Details', {
              itemId: Math.floor(Math.random() * 100),
            })
          }
        />
      </View>
    );
  }
}
```

> You can also directly access the params object with `this.props.navigation.state.params`. This may be `null` if no params were supplied, and so it's usually easier to just use `getParam` so you don't have to deal with that case.

> If you want to access the params directly through props (eg. `this.props.itemId`) rather than `this.props.navigation.getParam`, you may use a community-developed [react-navigation-props-mapper](https://github.com/vonovak/react-navigation-props-mapper) package.

## Summary

- `navigate` and `push` accept an optional second argument to let you pass parameters to the route you are navigating to. For example: `this.props.navigation.navigate('RouteName', {paramName: 'value'})`.
- You can read the params through `this.props.navigation.getParam`
- As an alternative to `getParam`, you may use `this.props.navigation.state.params`. It is `null` if no parameters are specified.

---

## Configuring the header bar

Source: https://reactnavigation.org/docs/4.x/headers

By now you're probably tired of seeing a blank grey bar on the top of your screen &mdash; you're ready for some [flair](https://memegenerator.net/img/images/600x600/14303485/stan-flair-office-space.jpg). So let's jump in to configuring the header bar.

## Setting the header title

A screen component can have a static property called `navigationOptions` which is either an object or a function that returns an object that contains various configuration options. The one we use for the header title is `title`, as demonstrated in the following example.

<samp id="basic-header-config">header title</samp>

```js
class HomeScreen extends React.Component {
  static navigationOptions = {
    title: 'Home',
  };

  /* render function, etc */
}

class DetailsScreen extends React.Component {
  static navigationOptions = {
    title: 'Details',
  };

  /* render function, etc */
}
```

> `createStackNavigator` uses platform conventions by default, so on iOS the title will be centered and on Android it will be left-aligned.

## Using params in the title

In order to use params in the title, we need to make `navigationOptions` a function that returns a configuration object. It might be tempting to try to use `this.props` inside of `navigationOptions`, but because it is a static property of the component, `this` does not refer to an instance of the component and therefore no props are available. Instead, if we make `navigationOptions` a function then React Navigation will call it with an object containing `{ navigation, navigationOptions, screenProps }` -- in this case, all we care about is `navigation`, which is the same object that is passed to your screen props as `this.props.navigation`. You may recall that we can get the params from `navigation` through `navigation.getParam` or `navigation.state.params`, and so we do this below to extract a param and use it as a title.

<samp id="params-in-title">params in title</samp>

```js
class DetailsScreen extends React.Component {
  static navigationOptions = ({ navigation }) => {
    return {
      title: navigation.getParam('otherParam', 'A Nested Details Screen'),
    };
  };

  /* render function, etc */
}
```

The argument that is passed in to the `navigationOptions` function is an object with the following properties:

- `navigation` - The [navigation prop](navigation-prop.md) for the screen, with the screen's route at `navigation.state`.
- `screenProps` - The props passing from above the navigator component
- `navigationOptions` - The default or previous options that would be used if new values are not provided

We only needed the `navigation` prop in the above example but you may in some cases want to use `screenProps` or `navigationOptions`.

## Updating `navigationOptions` with `setParams`

It's often necessary to update the `navigationOptions` configuration for the active screen from the mounted screen component itself. We can do this using `this.props.navigation.setParams`

<samp id="updating-options-with-setparams">updating navigationOptions</samp>

```js
/* Inside of render() */
<Button
  title="Update the title"
  onPress={() => this.props.navigation.setParams({ otherParam: 'Updated!' })}
/>
```

## Adjusting header styles

There are three key properties to use when customizing the style of your header: `headerStyle`, `headerTintColor`, and `headerTitleStyle`.

- `headerStyle`: a style object that will be applied to the `View` that wraps the header. If you set `backgroundColor` on it, that will be the color of your header.
- `headerTintColor`: the back button and title both use this property as their color. In the example below, we set the tint color to white (`#fff`) so the back button and the header title would be white.
- `headerTitleStyle`: if we want to customize the `fontFamily`, `fontWeight` and other `Text` style properties for the title, we can use this to do it.

<samp id="header-styles">header styles</samp>

```js
class HomeScreen extends React.Component {
  static navigationOptions = {
    title: 'Home',
    headerStyle: {
      backgroundColor: '#f4511e',
    },
    headerTintColor: '#fff',
    headerTitleStyle: {
      fontWeight: 'bold',
    },
  };

  /* render function, etc */
}
```

There are a couple of things to notice here:

1. On iOS, the status bar text and icons are black, and this doesn't look great over a dark-colored background. We won't discuss it here, but you should be sure to configure the status bar to fit with your screen colors [as described in the status bar guide](status-bar.md).
2. The configuration we set only applies to the home screen; when we navigate to the details screen, the default styles are back. We'll look at how to share `navigationOptions` between screens now.

## Sharing common `navigationOptions` across screens

It is common to want to configure the header in a similar way across many screens. For example, your company brand color might be red and so you want the header background color to be red and tint color to be white. Conveniently, these are the colors we're using in our running example, and you'll notice that when you navigate to the `DetailsScreen` the colors go back to the defaults. Wouldn't it be awful if we had to copy the `navigationOptions` header style properties from `HomeScreen` to `DetailsScreen`, and for every single screen component we use in our app? Thankfully, we do not. We can instead move the configuration up to the stack navigator under the property `defaultNavigationOptions`.

<samp id="sharing-header-styles">sharing header styles</samp>

```js
class HomeScreen extends React.Component {
  static navigationOptions = {
    title: 'Home',
    /* No more header config here! */
  };

  /* render function, etc */
}

/* other code... */

const AppNavigator = createStackNavigator(
  {
    Home: HomeScreen,
    Details: DetailsScreen,
  },
  {
    initialRouteName: 'Home',
    /* The header config from HomeScreen is now here */
    defaultNavigationOptions: {
      headerStyle: {
        backgroundColor: '#f4511e',
      },
      headerTintColor: '#fff',
      headerTitleStyle: {
        fontWeight: 'bold',
      },
    },
  }
);
```

Now, any screen that belongs to the `RootStack` will have our wonderful branded styles. Surely though, there must be a way to override these options if we need to?

> Note: In v2 and below, the property you would want to use to do this is `navigationOptions`. In v3 we've renamed this to `defaultNavigationOptions`.

The property `navigationOptions` can be used to configure the navigator itself:

<samp id="navigation-options-config" />

```js
const Home = createStackNavigator(
  {
    Feed: ExampleScreen,
    Profile: ExampleScreen,
  },
  {
    defaultNavigationOptions: {
      headerTintColor: '#fff',
      headerStyle: {
        backgroundColor: '#000',
      },
    },
    navigationOptions: {
      tabBarLabel: 'Home!',
    },
  }
);

const Tabs = createBottomTabNavigator({ Home });
```

## Overriding shared `navigationOptions`

The `navigationOptions` specified on your screen component are merged together with the default navigation options of its parent stack navigator, with the options on the screen component taking precedence. Let's use this knowledge to invert the background and tint colors on the details screen.

<samp id="overriding-shared-styles" />

```js
class DetailsScreen extends React.Component {
  static navigationOptions = ({ navigation, navigationOptions }) => {
    const { params } = navigation.state;

    return {
      title: params ? params.otherParam : 'A Nested Details Screen',
      /* These values are used instead of the shared configuration! */
      headerStyle: {
        backgroundColor: navigationOptions.headerTintColor,
      },
      headerTintColor: navigationOptions.headerStyle.backgroundColor,
    };
  };

  /* render function, etc */
}
```

## Replacing the title with a custom component

Sometimes you need more control than just changing the text and styles of your title -- for example, you may want to render an image in place of the title, or make the title into a button. In these cases you can completely override the component used for the title and provide your own.

<samp id="custom-header-title-component">custom header title component</samp>

```js
class LogoTitle extends React.Component {
  render() {
    return (
      <Image
        source={require('./spiro.png')}
        style={{ width: 30, height: 30 }}
      />
    );
  }
}

class HomeScreen extends React.Component {
  static navigationOptions = {
    // headerTitle instead of title
    headerTitle: () => <LogoTitle />,
  };

  /* render function, etc */
}
```

> You might be wondering, why `headerTitle` when we provide a component and not `title`, like before? The reason is that `headerTitle` is a property that is specific to a stack navigator, the `headerTitle` defaults to a `Text` component that displays the `title`.

## Additional configuration

You can read the full list of available `navigationOptions` for screens inside of a stack navigator in the [`createStackNavigator` reference](stack-navigator.md#navigationoptions-for-screens-inside-of-the-navigator).

## Summary

- You can customize the header inside of the `navigationOptions` static property on your screen components. Read the full list of options [in the API reference](stack-navigator.md#navigationoptions-for-screens-inside-of-the-navigator).
- The `navigationOptions` static property can be an object or a function. When it is a function, it is provided with an object with the `navigation` prop, `screenProps`, and `navigationOptions` on it.
- You can also specify shared `navigationOptions` in the stack navigator configuration when you initialize it. The static property takes precedence over that configuration.

---

## Header buttons

Source: https://reactnavigation.org/docs/4.x/header-buttons

Now that we know how to customize the look of our headers, let's make them sentient! Actually perhaps that's ambitious, let's just make them able to respond to our touches in very well defined ways.

## Adding a button to the header

The most common way to interact with a header is by tapping on a button either to the left or the right of the title. Let's add a button to the right side of the header (one of the most difficult places to touch on your entire screen, depending on finger and phone size, but also a normal place to put buttons).

<samp id="simple-header-button">header button</samp>

```js
class HomeScreen extends React.Component {
  static navigationOptions = {
    headerTitle: () => <LogoTitle />,
    headerRight: () => (
      <Button
        onPress={() => alert('This is a button!')}
        title="Info"
        color="#fff"
      />
    ),
  };
}
```

The binding of `this` in `navigationOptions` is _not_ the `HomeScreen` instance, so you can't call `setState` or any instance methods on it. This is pretty important because it's extremely common to want the buttons in your header to interact with the screen that the header belongs to. So, we will look how to do this next.

> Please note that a community-developed library for rendering buttons in the header with the correct styling is available: [react-navigation-header-buttons](https://github.com/vonovak/react-navigation-header-buttons).

## Header interaction with its screen component

The most commonly used pattern for giving a header button access to a function on the component instance is to use `params`. We'll demonstrate this with a classic example, the counter.

<samp id="header-interaction">header interaction</samp>

```js
class HomeScreen extends React.Component {
  static navigationOptions = ({ navigation }) => {
    return {
      headerTitle: () => <LogoTitle />,
      headerRight: () => (
        <Button
          onPress={navigation.getParam('increaseCount')}
          title="+1"
          color="#fff"
        />
      ),
    };
  };

  componentDidMount() {
    this.props.navigation.setParams({ increaseCount: this._increaseCount });
  }

  state = {
    count: 0,
  };

  _increaseCount = () => {
    this.setState({ count: this.state.count + 1 });
  };

  /* later in the render function we display the count */
}
```

> React Navigation doesn't guarantee that your screen component will be mounted before the header. Because the `increaseCount` param is set in `componentDidMount`, we may not have it available to us in `navigationOptions`. This usually will not be a problem because `onPress` for `Button` and `Touchable` components will do nothing if the callback is null. If you have your own custom component here, you should make sure it behaves as expected with `null` for its press handler prop.

> As an alternative to `setParams`, you could use a state management library (such as Redux or MobX) and communicate between the header and the screen in the same way you would with two distinct components.

## Customizing the back button

`createStackNavigator` provides the platform-specific defaults for the back button. On iOS this includes a label next to the button, which shows the title of the previous screen when the title fits in the available space, otherwise it says "Back".

You can change the label behavior with `headerBackTitle` and `headerTruncatedBackTitle` ([read more](stack-navigator.md#headerbacktitle)).

To customize the back button image, you can use [headerBackImage](stack-navigator.md#headerbackimage).

## Overriding the back button

The back button will be rendered automatically in a stack navigator whenever it is possible for the user to go back from their current screen &mdash; in other words, the back button will be rendered whenever there is more than one screen in the stack.

Generally, this is what you want. But it's possible that in some circumstances that you want to customize the back button more than you can through the options mentioned above, in which case you can set the `headerLeft` option to a React Element that will be rendered, just as we did with `headerRight`. Alternatively, the `headerLeft` option also accepts a React Component, which can be used, for example, for overriding the onPress behavior of the back button. Read more about this in the [api reference](stack-navigator.md#headerleft).

## Summary

- You can set buttons in the header through the `headerLeft` and `headerRight` properties in `navigationOptions`.
- The back button is fully customizable with `headerLeft`, but if you just want to change the title or image, there are other `navigationOptions` for that &mdash; `headerBackTitle`, `headerTruncatedBackTitle`, and `headerBackImage`.

---

## App containers

Source: https://reactnavigation.org/docs/4.x/app-containers

We've been taking `createAppContainer` for granted so far, so let's explain them quickly. Containers are responsible for managing your app state and linking your top-level navigator to the app environment. On Android, the app container uses the `Linking` API to handle the back button. The container can also be configured to persist your navigation state. On web, you'd use different containers than React Native. As we've seen already, app container usage looks like this:

```js
import { createAppContainer } from 'react-navigation';
import { createStackNavigator } from 'react-navigation-stack';

const RootStack = createStackNavigator({
  /* your routes here */
});
const AppContainer = createAppContainer(RootStack);

// Now AppContainer is the main component for React to render
export default AppContainer;
```

## Props of `createAppContainer` on React Native

There are a couple of props worth knowing about on the app container.

```js
<AppContainer
  onNavigationStateChange={handleNavigationChange}
  uriPrefix="/app"
/>
```

### `onNavigationStateChange(prevState, newState, action)`

Function that gets called every time navigation state managed by the navigator changes. It receives the previous state, the new state of the navigation and the action that issued state change. By default it prints state changes to the console.

### `uriPrefix`

The prefix of the URIs that the app might handle. This will be used when handling a [deep link](deep-linking.md) to extract the path passed to the router.

## Calling `dispatch` or `navigate` on a container ref

In some cases you may want to perform navigation actions from the root of your app, outside of any of the screens. To do this you can use a React [`ref`](https://facebook.github.io/react/docs/refs-and-the-dom.html#the-ref-callback-attribute) to call the `dispatch` method on it:

```js
const AppContainer = createAppContainer(AppNavigator);

class App extends React.Component {
  someEvent() {
    // call navigate for AppNavigator here:
    this.navigator &&
      this.navigator.dispatch(
        NavigationActions.navigate({ routeName: someRouteName })
      );
  }
  render() {
    return (
      <AppContainer
        ref={(nav) => {
          this.navigator = nav;
        }}
      />
    );
  }
}
```

## On the web

To learn about how to use React Navigation the web (still very experimental), see the [web support](web-support.md) guide.

---

## Opening a full-screen modal

Source: https://reactnavigation.org/docs/4.x/modal

Dictionary.com provides no satisfactory definition of modal as it relates to user interfaces, but semantic UI describes it as follows:

> A modal displays content that temporarily blocks interactions with the main view

This sounds about right. A modal is like a popup &mdash; it's not part of your primary navigation flow &mdash; it usually has a different transition, a different way to dismiss it, and is intended to focus on one particular piece of content or interaction.

The purpose of explaining this as part of the React Navigation fundamentals is not only because this is a common use case, but also because the implementation requires knowledge of _nesting navigators_, which is an important part of React Navigation.

## Creating a modal stack

<samp id="full-screen-modal">modal stack</samp>

```js
class HomeScreen extends React.Component {
  static navigationOptions = ({ navigation }) => {
    const params = navigation.state.params || {};

    return {
      headerLeft: () => (
        <Button
          onPress={() => navigation.navigate('MyModal')}
          title="Info"
          color="#fff"
        />
      ),
      /* the rest of this config is unchanged */
    };
  };

  /* render function, etc */
}

class ModalScreen extends React.Component {
  render() {
    return (
      <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
        <Text style={{ fontSize: 30 }}>This is a modal!</Text>
        <Button
          onPress={() => this.props.navigation.goBack()}
          title="Dismiss"
        />
      </View>
    );
  }
}

const MainStack = createStackNavigator(
  {
    Home: {
      screen: HomeScreen,
    },
    Details: {
      screen: DetailsScreen,
    },
  },
  {
    /* Same configuration as before */
  }
);

const RootStack = createStackNavigator(
  {
    Main: {
      screen: MainStack,
    },
    MyModal: {
      screen: ModalScreen,
    },
  },
  {
    mode: 'modal',
    headerMode: 'none',
  }
);
```

There are some important things to notice here:

- As we know, the stack navigator function returns a React component (remember we render `<RootStack />` in our `App` component). This same component can be used as a screen component! By doing this, we are nesting a stack navigator inside of another stack navigator. In this case, this is useful for us because we want to use a different transition style for the modal, and we want to disable the header across the entire stack. In the future this will be important because for tab navigation, for example, each tab will likely have its own stack! Intuitively, this is what you expect: when you are on tab A and switch to tab B, you would like tab A to maintain its navigation state as you continue to explore tab B. Look at this diagram to visualize the structure of navigation in this example:
  ![tree diagram](/assets/modal/tree.png)
- The `mode` configuration for stack navigator can be either `card` (default) or `modal`. The `modal` behavior slides the screen in from the bottom on iOS and allows the user to swipe down from the top to dismiss it. The `modal` configuration has no effect on Android because full-screen modals don't have any different transition behavior on the platform.
- When we call `navigate` we don't have to specify anything except the route that we'd like to navigate to. There is no need to qualify which stack it belongs to (the arbitrarily named 'root' or the 'main' stack) &mdash; React Navigation attempts to find the route on the closest navigator and then performs the action there. To visualize this, look again at [this diagram](/assets/modal/tree.png) and imagine the `navigate` action flowing up from `HomeScreen` to `MainStack`, we know that `MainStack` can't handle the route `MyModal`, so it then flows it up to `RootStack`, which can handle that route and so it does.

## Summary

- To change the type of transition on a stack navigator you can use the `mode` configuration. When set to `modal`, all screens animate-in from bottom to top rather than right to left. This applies to that entire stack navigator, so to use right to left transitions on other screens, we add another navigation stack with the default configuration.
- `this.props.navigation.navigate` traverses up the navigator tree to find a navigator that can handle the `navigate` action.

---

## Next steps

Source: https://reactnavigation.org/docs/4.x/next-steps

You are now familiar with how to create a stack navigator, configure it on your screen components, navigate between routes, and display full-screen modals. Stack navigator and its related APIs will be the most frequently used tools in your React Navigation toolbelt, but there are problems that they don't solve. For example, you can't build tab-based navigation using a stack navigator &mdash; for that, you need to use a [TabNavigator](tab-based-navigation.md).

The rest of the documentation is organized around specific use cases, so you can jump between the sections under "How do I do ...?" as the need arises (but it also wouldn't hurt you to familiarize yourself with them pre-emptively!).

While most users won't need to do this, if you are curious and want to learn more about how React Navigation works, it's recommended to work through the "Build your own Navigator" section.

Good luck!

---

## Glossary of terms

Source: https://reactnavigation.org/docs/4.x/glossary-of-terms

> This is a new section of the documentation and it's missing a lot of terms! Please [submit a pull request or an issue](https://github.com/react-navigation/website) with a term that you think should be explained here.

## Header

Also known as navigation header, navigation bar, navbar, and probably many other things. This is the rectangle at the top of your screen that contains the back button and the title for your screen. The entire rectangle is often referred to as the header in React Navigation.

## Screen component

A screen component is a component that we use in our route configuration.

```js
const AppNavigator = createStackNavigator(
  {
    Home: {
      screen: HomeScreen, // <----
    },
    Details: {
      screen: DetailsScreen, // <----
    },
  },
  {
    initialRouteName: 'Home',
  }
);
```

The suffix `Screen` in the component name is entirely optional, but a frequently used convention; we could call it `CasaPantalla` and this would work just the same.

We saw earlier that our screen components are provided with the `navigation` prop. It's important to note that _this only happens if the screen is rendered as a route by React Navigation_ (for example, in response to `this.props.navigation.navigate`). For example, if we render `DetailsScreen` as a child of `HomeScreen`, then `DetailsScreen` won't be provided with the `navigation` prop, and when you press the "Go to Details... again" button on the Home screen, the app will throw one of the quintessential JavaScript exceptions "undefined is not an object".

```js
class HomeScreen extends React.Component {
  render() {
    return (
      <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
        <Text>Home Screen</Text>
        <Button
          title="Go to Details"
          onPress={() => this.props.navigation.navigate('Details')}
        />
        <DetailsScreen />
      </View>
    );
  }
}
```

<a href="https://snack.expo.io/@react-navigation/screen-components-v3" target="blank" class="run-code-button">&rarr; Run this code</a>

The ["Navigation prop reference"](navigation-prop.md) section goes into more detail on this, describes workarounds, and provides more information on other properties available on `this.props.navigation`.

## Navigation Prop

This prop will be passed into all screens, and it can be used for the following:

- `dispatch` will send an action up to the router
- `state` is the current route for the screen
- `getParam` is a helper to access a param that may be on the route
- `navigate`, `goBack`, etc are available to dispatch actions in a convenient way

Navigators can also accept a navigation prop, which they should get from the parent navigator, if there is one.

For more details, see the ["Navigation prop document"](navigation-prop.md).

## Navigation State

The state of a navigator generally looks something like this:

```json
{
  "key": "StackRouterRoot",
  "index": 1,
  "routes": [
    { "key": "A", "routeName": "Home" },
    { "key": "B", "routeName": "Profile" }
  ]
}
```

For this navigation state, there are two routes (which may be tabs, or cards in a stack). The index indicates the active route, which is "B".

## Route

Each route is a piece of navigation state which contains a key to identify it, and a "routeName" to designate the type of route. It can also contain arbitrary params:

```json
{
  "key": "B",
  "routeName": "Profile",
  "params": { "id": "123" }
}
```

## Child Navigation State

When composing navigators, it is possible for a route to be a navigation state. It would look like this:

```json
{
  key: 'B',
  routeName: 'Profile',
  params: { id: '123' },
  index: 1,
  routes: [ {...}, {...} ]
}
```

---

## Common mistakes

Source: https://reactnavigation.org/docs/4.x/common-mistakes

This section attempts to outline issues that users frequently encounter when first getting accustomed to using React Navigation and serves as a reference in some cases for error messages.

## Explicitly rendering more than one navigator

Most apps should only ever render one navigator inside of a React component, and this is usually somewhere near the root component of your app. This is a little bit counter-intuitive at first but it's important for the architecture of React Navigation.

Here's what you might write in your code -- note that this example would be incorrect:

```javascript
export default class App extends React.Component {
  render() {
    /* In the root component we are rendering the app navigator */
    return <AppContainer />;
  }
}

const AuthenticationNavigator = createStackNavigator({
  SignIn: SignInScreen,
  ForgotPassword: ForgotPasswordScreen,
});

const AuthenticationContainer = createAppContainer(AuthenticationNavigator);

class AuthenticationScreen extends React.Component {
  render() {
    /*
     * In a screen inside of the navigator we are rendering another navigator
     * You should avoid this! It will have its own navigation state and be unable
     * To interact with any parent navigator, eg: it would not know the route "Home" exists
     */
    return <AuthenticationContainer />;
  }
}

const AppNavigator = createSwitchNavigator({
  Auth: AuthenticationScreen, // This screen renders a navigator!
  Home: HomeScreen,
});

const AppContainer = createAppContainer(AppNavigator);
```

The correct way to write this would be the following:

```javascript
export default class App extends React.Component {
  render() {
    return <AppContainer />;
  }
}

const AuthenticationNavigator = createStackNavigator({
  SignIn: SignInScreen,
  ForgotPassword: ForgotPasswordScreen,
});

const AppNavigator = createSwitchNavigator({
  /*
   * Rather than being rendered by a screen component, the
   * AuthenticationNavigator is a screen component
   */
  Auth: AuthenticationNavigator,
  Home: HomeScreen,
});

const AppContainer = createAppContainer(AppNavigator);
```

Alternatively, the following would also work because it exposes the `router` static on `AuthenticationScreen` and threads through the `navigation` prop:

```javascript
export default class App extends React.Component {
  render() {
    /* In the root component we are rendering the app navigator */
    return <AppContainer />;
  }
}

const AuthenticationNavigator = createStackNavigator({
  SignIn: SignInScreen,
  ForgotPassword: ForgotPasswordScreen,
});

class AuthenticationScreen extends React.Component {
  static router = AuthenticationNavigator.router;

  render() {
    return <AuthenticationNavigator navigation={this.props.navigation} />;
  }
}

const AppNavigator = createSwitchNavigator({
  Auth: AuthenticationScreen, // This screen renders a navigator!
  Home: HomeScreen,
});

const AppContainer = createAppContainer(AppNavigator);
```

## Assigning navigationOptions to the wrong component

In previous version of React Navigation, the library used to dig through your component tree to find `navigationOptions`. This is no longer the case, and only `navigationOptions` on screen components of a particular navigator will apply to that navigator. You can read more about this in the [Navigation options resolution](navigation-options-resolution.md) guide.

## Wrapping AppContainer in a View without flex: 1

If you wrap the `AppContainer` in a `View`, make sure the `View` is has `flex: 1` in the styles.

```javascript
import React from 'react';
import { Text, View } from 'react-native';
import { createAppContainer } from 'react-navigation';
import { createBottomTabNavigator } from 'react-navigation-tabs';

class HomeScreen extends React.Component {
  render() {
    return (
      <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
        <Text>Home!</Text>
      </View>
    );
  }
}

class SettingsScreen extends React.Component {
  render() {
    return (
      <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
        <Text>Settings!</Text>
      </View>
    );
  }
}

const TabNavigator = createBottomTabNavigator({
  Home: HomeScreen,
  Settings: SettingsScreen,
});

const AppContainer = createAppContainer(TabNavigator);

// without the style you will see a blank screen
export default () => (
  <View style={{ flex: 1 }}>
    <AppContainer />
  </View>
);
```

---

## Troubleshooting

Source: https://reactnavigation.org/docs/4.x/troubleshooting

This section attempts to outline issues that can happen during setup and may not be related to React Navigation itself. Also see [common mistakes](common-mistakes.md).

Before troubleshooting an issue, make sure that you have upgraded to **the latest available versions** of the packages. You can install the latest versions by installing the packages again (e.g. `npm install package-name`).

## I'm getting an error "Unable to resolve module" after updating to the latest version

This might happen for 2 reasons:

- Incorrect cache of Metro bundler
- Missing peer dependency

If the module points to a local file (i.e. the name of the module starts with `./`), then it's probably due to incorrect cache. To fix this, try the following solutions.

If you're using Expo, run:

```bash
expo start -c
```

If you're not using Expo, run:

```bash
npx react-native start --reset-cache
```

If the module points to an npm package (i.e. the name of the module doesn't with `./`), then it's probably due to a missing peer dependency. To fix this, install the dependency in your project:

```bash npm2yarn
npm install name-of-the-module
```

## I'm getting an error "null is not an object (evaluating 'RNGestureHandlerModule.default.Direction')"

This and some similar errors might occur if you didn't link the [`react-native-gesture-handler`](https://github.com/software-mansion/react-native-gesture-handler) library.

- **React Native 0.60 and higher**

  On newer versions of React Native, [linking is automatic](https://github.com/react-native-community/cli/blob/master/docs/autolinking.md), so if you have linked the library manually, first unlink it:

  ```bash
  react-native unlink react-native-gesture-handler
  ```

  If you're testing on iOS and use Mac, make sure you have run `pod install` in the `ios/` folder:

  ```bash
  cd ios; pod install; cd ..
  ```

- **React Native 0.59 and lower**

  If you're on an older React Native version, you need to manually link the library. To do that, run:

  ```bash
  react-native link react-native-gesture-handler
  ```

Now rebuild the app and test on your device or simulator.

## I'm getting an error "TypeError: Cannot read property 'bind' of undefined" or "TypeError: propListener.apply is not a function"

This error can often happen if you have a Babel plugin that compiles the code in a non-spec compliant way. For example:

```bash
["@babel/plugin-proposal-class-properties", { "loose": true}]
```

The above compiles class properties in `loose` mode, which is not spec compliant. To prevent such issues, avoid using any additional Babel plugins or presets which change the way Metro compiles code by default. Your `babel.config.js` should look like this:

```js
module.exports = {
  presets: ['module:metro-react-native-babel-preset'],
};
```

Or if you're using Expo:

```js
module.exports = {
  presets: ['babel-preset-expo'],
};
```

If you have additional options configured here, try removing them to see if it fixes the issue. After changing config, always clear the cache.

If you're using Expo, run:

```bash
expo start -c
```

If you're not using Expo, run:

```bash
npx react-native start --reset-cache
```

## I linked `react-native-gesture-handler` library but gestures won't work on Android

This might happen if you didn't update your MainActivity.java file (or wherever you create an instance of ReactActivityDelegate), so that it uses the root view wrapper provided by this library.

Check how to do it [here](https://software-mansion.github.io/react-native-gesture-handler/docs/getting-started.html).

## App is not working properly when connected to Chrome Debugger

When the app is connected to Chrome Debugger (or other tools that use Chrome Debugger such as [React Native Debugger](https://github.com/jhen0409/react-native-debugger)) you might encounter various issues related to timing.

This can result in issues such as button presses taking a long time to register or not working at all, [gestures and animations being slow and buggy](https://github.com/facebook/react-native/issues/2367) etc. There can be other functional issues such as promises not resolving, [timeouts and intervals not working correctly](https://github.com/facebook/react-native/issues/4470) etc. as well.

The issues are not related to React Navigation, but due to the nature of how the Chrome Debugger works. When connected to Chrome Debugger, your whole app runs on Chrome and communicates with the native app via sockets over the network, which can introduce latency and timing related issues.

So, unless you are trying to debug something, it's better to test the app without being connected to the Chrome Debugger. If you are using iOS, you can alternatively use [Safari to debug your app](https://reactnative.dev/docs/debugging#safari-developer-tools) which debugs the app on the device directly and does not have these issues, though it has other downsides.

---

## Limitations

Source: https://reactnavigation.org/docs/4.x/limitations

As a potential user of the library, it's important to know what you can and cannot do with it. Armed with this knowledge, you may choose to adopt [a different library instead](alternatives.md). We discuss the high level design decisions in the [pitch & anti-pitch](pitch.md) section, and here we will cover some of the use cases that are either not supported or are so difficult to do that they may as well be impossible. If any of the following limitations are dealbreakers for your app, React Navigation might not be for you.

## Dynamic routes

> It's not a limitation anymore with [React Navigation 5](https://reactnavigation.org) which uses a new component based API to be able to support this use case.

This one requires a bit of understanding of React Navigation to fully grok.

React Navigation requires that you define your routes statically, like so:

```js
const FriendsNavigator = createDrawerNavigator({
  Feed: FeedScreen,
  FriendList: FriendListScreen,
});

const AuthNavigator = createStackNavigator({
  SignIn: SignInScreen,
  ForgotPassword: ForgotPasswordScreen,
});

const AppNavigator = createSwitchNavigator({
  App: FriendsNavigator,
  Auth: AuthNavigator,
});

const AppContainer = createAppContainer(AppNavigator);

export default class MyApp extends React.Component {
  render() {
    return <AppContainer />;
  }
}
```

Let's say that when a user signs in to the app, you want to get a list of the user's friends and add a route for each friend in the `FriendsNavigator`. This would make it so there is a button with each of their names in the drawer. React Navigation does not currently provide an easy way to do this. React Navigation currently works best in situations where your routes can be defined statically. Keep in mind that this does not mean that you cannot pass arbitrary data to your routes &mdash; you can do this using [params](params.md).

There are workarounds if you absolutely need dynamic routes but you can expect some additional complexity.

## iOS 11 style header with large text

This is on the roadmap to implement, but it's not currently available in the React Navigation. Some folks have [gone ahead and built their own version of this](https://github.com/react-navigation/react-navigation/issues/2749#issuecomment-367516290), but your mileage may vary.

## Right-to-left (RTL) layout support

We try to handle RTL layouts properly in React Navigation, however the team working on React Navigation is fairly small and we do not have the bandwidth or processes at the moment to test all changes against RTL layouts. So you might encounter issues with RTL layouts.

If you like what React Navigation has to offer but are turned off by this constraint, we encourage you to get involved and take ownership of RTL layout support. Please reach out to us on Twitter: [@reactnavigation](https://twitter.com/reactnavigation).

## Performance limitations

We are able to offload animations to another thread using React Native's [Animated native driver](https://facebook.github.io/react-native/blog/2017/02/14/using-native-driver-for-animated.html), but we currently still need to call back into JavaScript for gestures (although there are plans to remedy this in the near future). React Navigation is entirely made up of React components and the state is managed in JavaScript on the same thread as the rest of your app. This is what makes React Navigation great in many ways but it also means that your app logic contends for CPU time with React Navigation &mdash; there's only so much JavaScript execution time available per frame.

## Nuanced platform-specific behavior

React Navigation does not include support for the peek & pop feature available on devices with 3D touch.

---

## Tab navigation

Source: https://reactnavigation.org/docs/4.x/tab-based-navigation

Possibly the most common style of navigation in mobile apps is tab-based navigation. This can be tabs on the bottom of the screen or on the top below the header (or even instead of a header).

This guide covers [`createBottomTabNavigator`](bottom-tab-navigator.md). You may also use [`createMaterialBottomTabNavigator`](material-bottom-tab-navigator.md) and [`createMaterialTopTabNavigator`](material-top-tab-navigator.md) to add tabs to your application.

## Minimal example of tab-based navigation

```js
import React from 'react';
import { Text, View } from 'react-native';
import { createAppContainer } from 'react-navigation';
import { createBottomTabNavigator } from 'react-navigation-tabs';

class HomeScreen extends React.Component {
  render() {
    return (
      <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
        <Text>Home!</Text>
      </View>
    );
  }
}

class SettingsScreen extends React.Component {
  render() {
    return (
      <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
        <Text>Settings!</Text>
      </View>
    );
  }
}

const TabNavigator = createBottomTabNavigator({
  Home: HomeScreen,
  Settings: SettingsScreen,
});

export default createAppContainer(TabNavigator);
```

<a href="https://snack.expo.io/@react-navigation/basic-tabs-v3" target="blank" class="run-code-button">&rarr; Run this code</a>

## Customizing the appearance

This is similar to how you would customize a stack navigator &mdash; there are some properties that are set when you initialize the tab navigator and others that can be customized per-screen in `navigationOptions`.

```js
// You can import Ionicons from @expo/vector-icons if you use Expo or
// react-native-vector-icons/Ionicons otherwise.
import Ionicons from 'react-native-vector-icons/Ionicons';
import { createAppContainer } from 'react-navigation';
import { createBottomTabNavigator } from 'react-navigation-tabs';

export default createBottomTabNavigator(
  {
    Home: HomeScreen,
    Settings: SettingsScreen,
  },
  {
    defaultNavigationOptions: ({ navigation }) => ({
      tabBarIcon: ({ focused, horizontal, tintColor }) => {
        const { routeName } = navigation.state;
        let IconComponent = Ionicons;
        let iconName;
        if (routeName === 'Home') {
          iconName = focused
            ? 'ios-information-circle'
            : 'ios-information-circle-outline';
          // Sometimes we want to add badges to some icons.
          // You can check the implementation below.
          IconComponent = HomeIconWithBadge;
        } else if (routeName === 'Settings') {
          iconName = focused ? 'ios-list-box' : 'ios-list';
        }

        // You can return any component that you like here!
        return <IconComponent name={iconName} size={25} color={tintColor} />;
      },
    }),
    tabBarOptions: {
      activeTintColor: 'tomato',
      inactiveTintColor: 'gray',
    },
  }
);
```

<a href="https://snack.expo.io/@react-navigation/tabs-with-icons-v3" target="blank" class="run-code-button">&rarr; Run this code</a>

Let's dissect this:

- `tabBarIcon` is a property on `navigationOptions`, so we know we can use it on our screen components, but in this case chose to put it in the `createBottomTabNavigator` configuration in order to centralize the icon configuration for convenience.
- `tabBarIcon` is a function that is given the `focused` state, `tintColor`, and `horizontal` param, which is a boolean. If you take a peek further down in the configuration you will see `tabBarOptions` and `activeTintColor` and `inactiveTintColor`. These default to the iOS platform defaults, but you can change them here. The `tintColor` that is passed through to the `tabBarIcon` is either the active or inactive one, depending on the `focused` state (focused is active). The orientation state `horizontal` is `true` when the device is in landscape, otherwise is `false` for portrait.
- Read the [full API reference](bottom-tab-navigator.md) for further information on `createBottomTabNavigator` configuration options.

## Add badges to icons

Sometimes we want to add badges to some icons. A common way is to use an extra view container and style the badge element with absolute positioning.

```js
export default class IconWithBadge extends React.Component {
  render() {
    const { name, badgeCount, color, size } = this.props;
    return (
      <View style={{ width: 24, height: 24, margin: 5 }}>
        <Ionicons name={name} size={size} color={color} />
        {badgeCount > 0 && (
          <View
            style={{
              // If you're using react-native < 0.57 overflow outside of parent
              // will not work on Android, see https://git.io/fhLJ8
              position: 'absolute',
              right: -6,
              top: -3,
              backgroundColor: 'red',
              borderRadius: 6,
              width: 12,
              height: 12,
              justifyContent: 'center',
              alignItems: 'center',
            }}
          >
            <Text style={{ color: 'white', fontSize: 10, fontWeight: 'bold' }}>
              {badgeCount}
            </Text>
          </View>
        )}
      </View>
    );
  }
}
```

From UI perspective this component is ready to use, but you still need to find some way to pass down the badge count properly from somewhere else, like using [React Context](https://reactjs.org/docs/context.html), [Redux](https://redux.js.org/), [MobX](https://mobx.js.org/) or [event emitters](https://github.com/facebook/react-native/blob/master/Libraries/vendor/emitter/EventEmitter.js).

```js
const HomeIconWithBadge = (props) => {
  // You should pass down the badgeCount in some other ways like React Context API, Redux, MobX or event emitters.
  return <IconWithBadge {...props} badgeCount={3} />;
};
export default HomeIconWithBadge;
```

## Jumping between tabs

Switching from one tab to another has a familiar API &mdash; `this.props.navigation.navigate`.

```js
import { Button, Text, View } from 'react-native';

class HomeScreen extends React.Component {
  render() {
    return (
      <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
        <Text>Home!</Text>
        <Button
          title="Go to Settings"
          onPress={() => this.props.navigation.navigate('Settings')}
        />
      </View>
    );
  }
}

class SettingsScreen extends React.Component {
  render() {
    return (
      <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
        <Text>Settings!</Text>
        <Button
          title="Go to Home"
          onPress={() => this.props.navigation.navigate('Home')}
        />
      </View>
    );
  }
}
```

<a href="https://snack.expo.io/@react-navigation/jumping-between-tabs-v3" target="blank" class="run-code-button">&rarr; Run this code</a>

## A stack navigator for each tab

Usually tabs don't just display one screen &mdash; for example, on your Twitter feed, you can tap on a tweet and it brings you to a new screen within that tab with all of the replies. You can think of this as there being separate navigation stacks within each tab, and that's exactly how we will model it in React Navigation.

```js
import { createAppContainer } from 'react-navigation';
import { createStackNavigator } from 'react-navigation-stack';
import { createBottomTabNavigator } from 'react-navigation-tabs';

class DetailsScreen extends React.Component {
  render() {
    return (
      <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
        <Text>Details!</Text>
      </View>
    );
  }
}

class HomeScreen extends React.Component {
  render() {
    return (
      <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
        {/* other code from before here */}
        <Button
          title="Go to Details"
          onPress={() => this.props.navigation.navigate('Details')}
        />
      </View>
    );
  }
}

class SettingsScreen extends React.Component {
  render() {
    return (
      <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
        {/* other code from before here */}
        <Button
          title="Go to Details"
          onPress={() => this.props.navigation.navigate('Details')}
        />
      </View>
    );
  }
}

const HomeStack = createStackNavigator({
  Home: HomeScreen,
  Details: DetailsScreen,
});

const SettingsStack = createStackNavigator({
  Settings: SettingsScreen,
  Details: DetailsScreen,
});

export default createAppContainer(
  createBottomTabNavigator(
    {
      Home: HomeStack,
      Settings: SettingsStack,
    },
    {
      /* Other configuration remains unchanged */
    }
  )
);
```

<a href="https://snack.expo.io/@react-navigation/stacks-in-tabs-v3" target="blank" class="run-code-button">&rarr; Run this code</a>

## Why do we need a TabNavigator instead of TabBarIOS or some other component?

It's common to attempt to use a standalone tab bar component without integrating it into the navigation library you use in your app. In some cases, this works fine! You should be warned, however, that you may run into some frustrating unanticipated issues when doing this.

For example, React Navigation's `TabNavigator` takes care of handling the Android back button for you, while standalone components typically do not. Additionally, it is more difficult for you (as the developer) to perform actions such as "jump to this tab and then go to this screen" if you need to call into two distinct APIs for it. Lastly, mobile user interfaces have numerous small design details that require that certain components are aware of the layout or presence of other components &mdash; for example, if you have a translucent tab bar, content should scroll underneath it and the scroll view should have an inset on the bottom equal to the height of the tab bar so you can see all of the content. Double tapping the tab bar should make the active navigation stack pop to the top of the stack, and doing it again should scroll the active scroll view in that stack scroll to the top. While not all of these behaviors are implemented out of the box yet with React Navigation, they will be and you will not get any of this if you use a standalone tab view component.

## A tab navigator contains a stack and you want to hide the tab bar on specific screens

[See the documentation here](navigation-options-resolution.md#a-tab-navigator-contains-a-stack-and-you-want-to-hide-the-tab-bar-on-specific-screens)

---

## Drawer navigation

Source: https://reactnavigation.org/docs/4.x/drawer-based-navigation

This guide covers [createDrawerNavigator](drawer-navigator.md).

```js
class MyHomeScreen extends React.Component {
  static navigationOptions = {
    drawerLabel: 'Home',
    drawerIcon: ({ tintColor }) => (
      <Image
        source={require('./chats-icon.png')}
        style={[styles.icon, { tintColor: tintColor }]}
      />
    ),
  };

  render() {
    return (
      <Button
        onPress={() => this.props.navigation.navigate('Notifications')}
        title="Go to notifications"
      />
    );
  }
}

class MyNotificationsScreen extends React.Component {
  static navigationOptions = {
    drawerLabel: 'Notifications',
    drawerIcon: ({ tintColor }) => (
      <Image
        source={require('./notif-icon.png')}
        style={[styles.icon, { tintColor: tintColor }]}
      />
    ),
  };

  render() {
    return (
      <Button
        onPress={() => this.props.navigation.goBack()}
        title="Go back home"
      />
    );
  }
}

const styles = StyleSheet.create({
  icon: {
    width: 24,
    height: 24,
  },
});

const MyDrawerNavigator = createDrawerNavigator({
  Home: {
    screen: MyHomeScreen,
  },
  Notifications: {
    screen: MyNotificationsScreen,
  },
});

const MyApp = createAppContainer(MyDrawerNavigator);
```

To open and close drawer, use the following helpers to open and close the drawer:

```js
this.props.navigation.openDrawer();
this.props.navigation.closeDrawer();
```

If you would like to toggle the drawer you call the following:

```js
this.props.navigation.toggleDrawer();
```

Each of these functions, behind the scenes, are simply dispatching actions:

```js
this.props.navigation.dispatch(DrawerActions.openDrawer());
this.props.navigation.dispatch(DrawerActions.closeDrawer());
this.props.navigation.dispatch(DrawerActions.toggleDrawer());
```

If you would like to determine if drawer is open or closed, you can do the following:

```js
const parent = this.props.navigation.dangerouslyGetParent();
const isDrawerOpen = parent && parent.state && parent.state.isDrawerOpen;
```

---

## Authentication flows

Source: https://reactnavigation.org/docs/4.x/auth-flow

Most apps require that a user authenticate in some way to have access to data associated with a user or other private content. Typically the flow will look like this:

- The user opens the app.
- The app loads some authentication state from persistent storage (for example, `AsyncStorage`).
- When the state has loaded, the user is presented with either authentication screens or the main app, depending on whether valid authentication state was loaded.
- When the user signs out, we clear the authentication state and send them back to authentication screens.

> Note: we say "authentication screens" because usually there is more than one. You may have a main screen with a username and password field, another for "forgot password", and another set for sign up.

## Set up our navigators

```js
import { createAppContainer, createSwitchNavigator } from 'react-navigation';
import { createStackNavigator } from 'react-navigation-stack';

// Implementation of HomeScreen, OtherScreen, SignInScreen, AuthLoadingScreen
// goes here.

const AppStack = createStackNavigator({ Home: HomeScreen, Other: OtherScreen });
const AuthStack = createStackNavigator({ SignIn: SignInScreen });

export default createAppContainer(
  createSwitchNavigator(
    {
      AuthLoading: AuthLoadingScreen,
      App: AppStack,
      Auth: AuthStack,
    },
    {
      initialRouteName: 'AuthLoading',
    }
  )
);
```

You may not be familiar with `SwitchNavigator` yet. The purpose of `SwitchNavigator` is to only ever show one screen at a time. By default, it does not handle back actions and it resets routes to their default state when you switch away. This is the exact behavior that we want from the authentication flow: when users sign in, we want to throw away the state of the authentication flow and unmount all of the screens, and when we press the hardware back button we expect to not be able to go back to the authentication flow. We switch between routes in the `SwitchNavigator` by using the `navigate` action. You can read more about the `SwitchNavigator` in the [API reference](switch-navigator.md).

We set the `initialRouteName` to `'AuthLoading'` because we will fetch our authentication state from persistent storage inside of that screen component.

## Implement our authentication loading screen

```js
import React from 'react';
import {
  ActivityIndicator,
  AsyncStorage,
  StatusBar,
  StyleSheet,
  View,
} from 'react-native';

class AuthLoadingScreen extends React.Component {
  componentDidMount() {
    this._bootstrapAsync();
  }

  // Fetch the token from storage then navigate to our appropriate place
  _bootstrapAsync = async () => {
    const userToken = await AsyncStorage.getItem('userToken');

    // This will switch to the App screen or Auth screen and this loading
    // screen will be unmounted and thrown away.
    this.props.navigation.navigate(userToken ? 'App' : 'Auth');
  };

  // Render any loading content that you like here
  render() {
    return (
      <View>
        <ActivityIndicator />
        <StatusBar barStyle="default" />
      </View>
    );
  }
}
```

## Fill in other components

Our `App` and `Auth` routes are both stack navigators, but you could do whatever you like here. As mentioned above, you probably want your authentication route to be a stack for password reset, signup, etc. Similarly for your app, you probably have more than one screen. We won't talk about how to implement the text inputs and buttons for the authentication screen, that is outside of the scope of navigation. We'll just fill in some placeholder content.

<samp id="auth-flow">Auth Flow</samp>

```js
class SignInScreen extends React.Component {
  static navigationOptions = {
    title: 'Please sign in',
  };

  render() {
    return (
      <View>
        <Button title="Sign in!" onPress={this._signInAsync} />
      </View>
    );
  }

  _signInAsync = async () => {
    await AsyncStorage.setItem('userToken', 'abc');
    this.props.navigation.navigate('App');
  };
}

class HomeScreen extends React.Component {
  static navigationOptions = {
    title: 'Welcome to the app!',
  };

  render() {
    return (
      <View>
        <Button title="Show me more of the app" onPress={this._showMoreApp} />
        <Button title="Actually, sign me out :)" onPress={this._signOutAsync} />
      </View>
    );
  }

  _showMoreApp = () => {
    this.props.navigation.navigate('Other');
  };

  _signOutAsync = async () => {
    await AsyncStorage.clear();
    this.props.navigation.navigate('Auth');
  };
}

// More code like OtherScreen omitted for brevity
```

That's about all there is to it. If you're interested in animating the switch between screens, you can read about `createAnimatedSwitchNavigator` in the [API reference](animated-switch-navigator.md).

---

## Supporting safe areas

Source: https://reactnavigation.org/docs/4.x/handling-iphonex

By default, React Navigation tries to ensure that the elements of the navigators display correctly on devices with notches (e.g. iPhone X) and UI elements which may overlap the app content. Such items include:

- Physical notches
- Status bar overlay
- Home activity indicator on iOS
- Navigation bar on Android

The area not overlapped by such items is referred to as "safe area".

We try to apply proper insets on the UI elements of the navigators to avoid being overlapped by such items. The goal is to (a) maximize usage of the screen (b) without hiding content or making it difficult to interact with by having it obscured by a physical display cutout or some operating system UI.

While React Navigation handles safe areas for the built-in UI elements by default, your own content also needs to handle it to ensure that content isn't hidden by these items.

It's tempting to solve (a) by wrapping your entire app in a container with padding that ensures all content will not be occluded. But in doing so, we waste a bunch of space on the screen, as pictured in the image on the left below. What we ideally want is the image pictured on the right.

![Notch on the iPhone X](/assets/iphoneX/00-intro.png)

While React Native exports a `SafeAreaView` component, it has some inherent issues, i.e. if a screen containing safe area is animating, it causes jumpy behavior. In addition, this component only supports iOS 10+ with no support for older iOS versions or Android. We recommend to use the [react-native-safe-area-context](https://github.com/th3rdwave/react-native-safe-area-context) library to handle safe areas in a more reliable way.

The rest of this guide gives more information on how to support safe areas in React Navigation.

## Hidden/Custom Navigation Bar or Tab Bar

![Default React Navigation Behavior](/assets/iphoneX/01-iphonex-default.png)

React Navigation handles safe area in the default header. However, if you're using a custom header, it's important to ensure your UI is within the safe area.

For example, if I render nothing for the `header` or `tabBarComponent`, nothing renders

```jsx
const Tabs = createBottomTabNavigator({
  ...
}, {
  tabBarComponent: () => null,
});

export default createStackNavigator({
  ...
}, {
  headerMode: 'none',
});
```

![Text hidden by iPhoneX UI elements](/assets/iphoneX/02-iphonex-content-hidden.png)

To fix this issue you can apply safe area insets on your content. This can be achieved easily by using the `SafeAreaView` component from the `react-native-safe-area-context` library. Recall that `SafeAreaView` should not wrap entire navigators, just the content inside the screen.

```jsx
import { SafeAreaView } from 'react-native-safe-area-context';

class MyHomeScreen extends Component {
  render() {
    return (
      <SafeAreaView style={styles.container}>
        <Text style={styles.paragraph}>This is top text.</Text>
        <Text style={styles.paragraph}>This is bottom text.</Text>
      </SafeAreaView>
    );
  }
}
```

Make sure to wrap your app in `SafeAreaProvider` as per the instructions [here](https://github.com/th3rdwave/react-native-safe-area-context#usage).

![Content spaced correctly with SafeAreaView](/assets/iphoneX/03-iphonex-content-fixed.png)

This will detect if the app is running on an iPhoneX and, if so, ensure the content isn't hidden behind any hardware elements.

## Landscape Mode

Even if you're using the default navigation bar and tab bar if your application works in landscape mode it's important to ensure you content isn't hidden behind the sensor cluster.

![App in landscape mode with text hidden](/assets/iphoneX/04-iphonex-landscape-hidden.png)

To fix this you can, once again, wrap your content in a `SafeAreaView`. This will not conflict with the navigation bar nor the tab bar's default behavior in portrait mode.

![App in landscape mode with text visible](/assets/iphoneX/05-iphonex-landscape-fixed.png)

In conclusion, use the `SafeAreaView` component on the screens you register with a React Navigation navigator.

## Use the `edges` prop to customize the safe area

In some cases you might need more control over which paddings are applied. For example, you can remove bottom padding by passing `edges` prop to `SafeAreaView`.

```jsx
<SafeAreaView style={styles.container} edges={['top', 'left', 'right']}>
  <Text style={styles.paragraph}>This is top text.</Text>
  <Text style={styles.paragraph}>This is bottom text.</Text>
</SafeAreaView>
```

`edges` takes an array with the values `top`, `bottom`, `left` and `right` which controls which sides the safe area are applied to.

## Use the hook for more control

In some cases you might need more control over which paddings are applied. For example, you can only apply the top and the bottom padding by changing the `style` object:

```jsx
import { useSafeAreaInsets } from 'react-native-safe-area-context';

function Demo() {
  const insets = useSafeAreaInsets();

  return (
    <View
      style={{
        paddingTop: insets.top,
        paddingBottom: insets.bottom,

        flex: 1,
        justifyContent: 'space-between',
        alignItems: 'center',
      }}
    >
      <Text>This is top text.</Text>
      <Text>This is bottom text.</Text>
    </View>
  );
}
```

Similarly, you could apply these paddings in `contentContainerStyle` of `FlatList` to have the content avoid the safe areas, but still show them under the statusbar and navigation bar when scrolling.

## Summary

- Use `react-native-safe-area-context` instead of `SafeAreaView` from `react-native`
- Don't wrap your whole app in `SafeAreaView`, instead wrap content inside your screens
- Use the `edges` prop to apply safe area to specific sides
- Use the `useSafeAreaInsets` hook for more control over where the insets are applied

---

## Different status bar configuration based on route

Source: https://reactnavigation.org/docs/4.x/status-bar

If you don't have a navigation header, or your navigation header changes color based on the route, you'll want to ensure that the correct color is used for the content.

## Stack and drawer navigators

This is a simple task when using a stack or drawer. You can simply render the `StatusBar` component, which is exposed by React Native, and set your config.

```jsx
class Screen1 extends React.Component {
  render() {
    return (
      <SafeAreaView style={[styles.container, { backgroundColor: '#6a51ae' }]}>
        <StatusBar barStyle="light-content" backgroundColor="#6a51ae" />
        <Text style={[styles.paragraph, { color: '#fff' }]}>Light Screen</Text>
        <Button
          title="Next screen"
          onPress={() => this.props.navigation.navigate('Screen2')}
          color={isAndroid ? 'blue' : '#fff'}
        />
      </SafeAreaView>
    );
  }
}

class Screen2 extends React.Component {
  render() {
    return (
      <SafeAreaView style={[styles.container, { backgroundColor: '#ecf0f1' }]}>
        <StatusBar barStyle="dark-content" backgroundColor="#ecf0f1" />
        <Text style={styles.paragraph}>Dark Screen</Text>
        <Button
          title="Next screen"
          onPress={() => this.props.navigation.navigate('Screen1')}
        />
      </SafeAreaView>
    );
  }
}
```

```jsx
export default createStackNavigator(
  {
    Screen1: {
      screen: Screen1,
    },
    Screen2: {
      screen: Screen2,
    },
  },
  {
    headerMode: 'none',
  }
);
```

![StackNavigator with different StatusBar configs](/assets/statusbar/statusbar-stack-demo.gif)

```jsx
export default createDrawerNavigator({
  Screen1: {
    screen: Screen1,
  },
  Screen2: {
    screen: Screen2,
  },
});
```

![DrawerNavigator with different StatusBar configs](/assets/statusbar/statusbar-drawer-demo.gif)

## Tabs and Drawer

If you're using a tab or drawer navigator, it's a bit more complex because all of the screens in the navigator might be rendered at once and kept rendered - that means that the last `StatusBar` config you set will be used (likely on the final tab of your tab navigator, not what the user is seeing).

To fix this, we'll have to do make the status bar component aware of screen focus and render it only when the screen is focused. We can achieve this by using the [`withNavigationFocus` HOC](with-navigation-focus.md) and creating a wrapper component:

```js
import * as React from 'react';
import { StatusBar } from 'react-native';
import { withNavigationFocus } from 'react-navigation';

const FocusAwareStatusBar = withNavigationFocus(({ isFocused, ...rest }) =>
  isFocused ? <StatusBar {...rest} /> : null
);
```

Now, our screens (both `Screen1.js` and `Screen2.js`) will use the `FocusAwareStatusBar` component instead of the `StatusBar` component from React Native:

```jsx
class Screen1 extends React.Component {
  render() {
    return (
      <SafeAreaView style={[styles.container, { backgroundColor: '#6a51ae' }]}>
        <FocusAwareStatusBar
          barStyle="light-content"
          backgroundColor="#6a51ae"
        />
        <Text style={[styles.paragraph, { color: '#fff' }]}>Light Screen</Text>
        <Button
          title="Next screen"
          onPress={() => this.props.navigation.navigate('Screen2')}
          color={isAndroid ? 'blue' : '#fff'}
        />
      </SafeAreaView>
    );
  }
}

class Screen2 extends React.Component {
  render() {
    return (
      <SafeAreaView style={[styles.container, { backgroundColor: '#ecf0f1' }]}>
        <FocusAwareStatusBar
          barStyle="dark-content"
          backgroundColor="#ecf0f1"
        />
        <Text style={styles.paragraph}>Dark Screen</Text>
        <Button
          title="Next screen"
          onPress={() => this.props.navigation.navigate('Screen1')}
        />
      </SafeAreaView>
    );
  }
}
```

Although not necessary, you can use the `FocusAwareStatusBar` component in the screens of the stack navigator as well.

![TabNavigator with different StatusBar configs](/assets/statusbar/statusbar-tab-demo.gif)

---

## Navigation options resolution

Source: https://reactnavigation.org/docs/4.x/navigation-options-resolution

Each screen can configure various aspects about how it gets presented in the navigator that renders it. In the [Configuring the header bar](headers.md) section of the fundamentals documentation we explain the basics of how this works.

In this document we'll explain how this works when there are multiple navigators. It's important to understand this so that you put your `navigationOptions` in the correct place and can properly configure your navigators. If you put them in the wrong place, at best nothing will happen and at worst something confusing and unexpected will happen. Thankfully, the logic for this could not be any easier to understand:

**You can only modify navigation options for a navigator from one of its screen components. This applies equally to navigators that are nested as screens.**

Let's take for example a tab navigator that contains a stack in each tab. What happens if we set the `navigationOptions` on a screen inside of the stack?

```js
class A extends React.Component {
  static navigationOptions = {
    tabBarLabel: 'Home!',
  };

  // etc..
}

class B extends React.Component {
  static navigationOptions = {
    tabBarLabel: 'Settings!',
  };

  // etc..
}

const HomeStack = createStackNavigator({ A });
const SettingsStack = createStackNavigator({ B });

export default createAppContainer(
  createBottomTabNavigator({
    HomeStack,
    SettingsStack,
  })
);
```

<a href="https://snack.expo.io/@react-navigation/nested-navigationoptions-wrong-v3" target="blank" class="run-code-button">&rarr; Run this code</a>

As we mentioned earlier, you can only modify navigation options for a navigator from one of its screen components. `A` and `B` above are screen components in `HomeStack` and `SettingsStack` respectively, not in the tab navigator. So the result will be that the `tabBarLabel` property is not applied to the tab navigator. We can fix this though!

```js
const HomeStack = createStackNavigator({ A });
const SettingsStack = createStackNavigator({ B });

HomeStack.navigationOptions = {
  tabBarLabel: 'Home!',
};

SettingsStack.navigationOptions = {
  tabBarLabel: 'Settings!',
};

export default createAppContainer(
  createBottomTabNavigator({
    HomeStack,
    SettingsStack,
  })
);
```

<a href="https://snack.expo.io/@react-navigation/nested-navigationoptions-correct-v3" target="blank" class="run-code-button">&rarr; Run this code</a>

To understand what is going on here, first recall that in the following example, `MyComponent` and `MyOtherComponent` are identical:

```js
class MyComponent extends React.Component {
  static navigationOptions = {
    title: 'Hello!',
  };
  // etc.
}

class MyOtherComponent extends React.Component {
  // etc.
}

MyOtherComponent.navigationOptions = {
  title: 'Hello!',
};
```

We also know that `createStackNavigator` and related functions return React components. So when we set the `navigationOptions` directly on the `HomeStack` and `SettingsStack` component, it allows us to control the `navigationOptions` for its parent navigator when its used as a screen component. In this case, the `navigationOptions` on our stack components configure the label in the tab navigator that renders the stacks.

```js
const HomeStack = createStackNavigator(
  { A },
  {
    // This is the default for screens in the stack, so `A` will
    // use this title unless it overrides it
    defaultNavigationOptions: {
      title: 'Welcome',
    },
  }
);

// These are the options that are used by the navigator that renders
// the HomeStack, in our example above this is a tab navigator.
HomeStack.navigationOptions = {
  tabBarLabel: 'Home!',
};
```

Another way you could write this is:

```js
const HomeStack = createStackNavigator(
  { A },
  {
    // This applies to the parent navigator
    navigationOptions: {
      tabBarLabel: 'Home!',
    },
    // This applies to child routes
    defaultNavigationOptions: {
      title: 'Welcome',
    },
  }
);
```

<a href="https://snack.expo.io/@react-navigation/nested-navigationoptions-title-v3" target="blank" class="run-code-button">&rarr; Run this code</a>

## getActiveChildNavigationOptions

If you would like to get the `navigationOptions` from the active child of a navigator, you can do that with `getActiveChildNavigationOptions`. This makes it possible for you to set the `tabBarLabel` directly on a screen inside of a stack that is inside of a tab, for example.

```jsx
class A extends React.Component {
  static navigationOptions = {
    title: 'Welcome',
    tabBarLabel: 'Home!',
  };

  render() {
    return <Placeholder text="A!" />;
  }
}

const HomeStack = createStackNavigator(
  { A },
  {
    navigationOptions: ({ navigation, screenProps }) => ({
      // you can put fallback values before here, eg: a default tabBarLabel
      ...getActiveChildNavigationOptions(navigation, screenProps),
      // put other navigationOptions that you don't want the active child to
      // be able to override here!
    }),
  }
);
```

<a href="https://snack.expo.io/@react-navigation/nested-navigationoptions-active-child-v3" target="blank" class="run-code-button">&rarr; Run this code</a>

## **Note**: the navigationOptions property vs navigator configuration

Navigators are initialized with `create*Navigator(routeConfig, navigatorConfig)`. Inside of `navigatorConfig` we can add a `defaultNavigationOptions` property. These `defaultNavigationOptions` are the default options for screens within that navigator ([read more about sharing common navigationOptions](headers.md#sharing-common-navigationoptions-across-screens)), they do not refer to the `navigationOptions` for that navigator &mdash; as we have seen above, we set the `navigationOptions` property directly on the navigator for that use case.

## A stack contains a tab navigator and you want to set the title on the stack header

Imagine the following configuration:

```js
const TabNavigator = createBottomTabNavigator({
  Feed: FeedScreen,
  Profile: ProfileScreen,
});

const AppNavigator = createStackNavigator({
  Home: TabNavigator,
  Settings: SettingsScreen,
});
```

If we were to set the `headerTitle` with `navigationOptions` on the `FeedScreen`, this would not work. This is because the `AppNavigator` stack will only look at its immediate children for configuration: `TabNavigator` and `SettingsScreen`. So we can set the `headerTitle` on the `TabNavigator` instead, like so:

```js
const TabNavigator = createBottomTabNavigator({
  Feed: FeedScreen,
  Profile: ProfileScreen,
});

TabNavigator.navigationOptions = ({ navigation }) => {
  const { routeName } = navigation.state.routes[navigation.state.index];

  // You can do whatever you like here to pick the title based on the route name
  const headerTitle = routeName;

  return {
    headerTitle,
  };
};
```

Another option is to re-organize your navigators, such that each tab has its own stack. You can then hide the top-level stack's header when the tab screen is focused.

```js
const FeedStack = createStackNavigator({
  FeedHome: FeedScreen,
  /* other routes here */
});

const ProfileStack = createStackNavigator({
  ProfileHome: ProfileScreen,
  /* other routes here */
});

const TabNavigator = createBottomTabNavigator({
  Feed: FeedStack,
  Profile: ProfileStack,
});

TabNavigator.navigationOptions = {
  // Hide the header from AppNavigator stack
  headerShown: false,
};

const AppNavigator = createStackNavigator({
  Home: TabNavigator,
  Settings: SettingsScreen,
});
```

Using this configuration, the `headerTitle` or `title` from `navigationOptions` on `FeedScreen` and `ProfileScreen` will not determine the title in their headers.

Additionally, you can push new screens to the feed and profile stacks without hiding the tab bar by adding more routes to those stacks. If you want to push screens on top of the tab bar, then you can add them to the `AppNavigator` stack.

## A tab navigator contains a stack and you want to hide the tab bar on specific screens

Similar to the example above where a stack contains a tab navigator, we can solve this in two ways: add `navigationOptions` to our tab navigator to set the tab bar to hidden depending on which route is active in the child stack, or we can move the tab navigator inside of the stack.

Imagine the following configuration:

```js
const FeedStack = createStackNavigator({
  FeedHome: FeedScreen,
  Details: DetailsScreen,
});

const TabNavigator = createBottomTabNavigator({
  Feed: FeedStack,
  Profile: ProfileScreen,
});

const AppNavigator = createSwitchNavigator({
  Auth: AuthScreen,
  Home: TabNavigator,
});
```

If we want to hide the tab bar when we navigate from the feed home to a details screen without shuffling navigators, we cannot set the `tabBarVisible: false` configuration in `navigationOptions` on `DetailsScreen`, because those options will only apply to the `FeedStack`. Instead, we can do the following:

```js
const FeedStack = createStackNavigator({
  FeedHome: FeedScreen,
  Details: DetailsScreen,
});

FeedStack.navigationOptions = ({ navigation }) => {
  let tabBarVisible = true;
  if (navigation.state.index > 0) {
    tabBarVisible = false;
  }

  return {
    tabBarVisible,
  };
};
```

This will hide the tab bar any time we navigate away from the feed home. We could switch visibility based on route name, but it would be strange to have the tab bar be hidden and then appear again when pushing another route &mdash; it should only be visible when returning to a route where it was previously visible.

Another option here would be to add another stack navigator as a parent of the tab navigator, and put the details screen there. This is recommended.

```js
const FeedStack = createStackNavigator({
  FeedHome: FeedScreen,
  /* any other route you want to render under the tab bar */
});

const TabNavigator = createBottomTabNavigator({
  Feed: FeedStack,
  Profile: ProfileScreen,
});

const HomeStack = createStackNavigator({
  Tabs: TabNavigator,
  Details: DetailsScreen,
  /* any other route you want to render above the tab bar */
});

const AppNavigator = createSwitchNavigator({
  Auth: AuthScreen,
  Home: HomeStack,
});
```

## A drawer has a stack inside of it and you want to lock the drawer on certain screens

This is conceptually identical to having a tab with a stack inside of it (read that above if you have not already), where you want to hide the tab bar on certain screens. The only difference is that rather than using `tabBarVisible` you will use `drawerLockMode`.

Imagine the following configuration:

```js
const FeedStack = createStackNavigator({
  FeedHome: FeedScreen,
  Details: DetailsScreen,
});

const DrawerNavigator = createDrawerNavigator({
  Feed: FeedStack,
  Profile: ProfileScreen,
});

const AppNavigator = createSwitchNavigator({
  Auth: AuthScreen,
  Home: DrawerNavigator,
});
```

In order to hide the drawer when we push the details screen to the feed stack, we need to set `navigationOptions` on the `FeedStack`. If we were to set `navigationOptions` on the `DetailsScreen`, they would be configuring the feed stack (its direct parent) and not the drawer.

```js
const FeedStack = createStackNavigator({
  FeedHome: FeedScreen,
  Details: DetailsScreen,
});

FeedStack.navigationOptions = ({ navigation }) => {
  let drawerLockMode = 'unlocked';
  if (navigation.state.index > 0) {
    drawerLockMode = 'locked-closed';
  }

  return {
    drawerLockMode,
  };
};
```

Another option here would be to add another stack navigator as a parent of the drawer navigator, and put the details screen there. This is recommended.

```js
const FeedStack = createStackNavigator({
  FeedHome: FeedScreen,
  /* any other route where you want the drawer to remain available */
  /* keep in mind that it will conflict with the swipe back gesture on ios */
});

const DrawerNavigator = createDrawerNavigator({
  Feed: FeedStack,
  Profile: ProfileScreen,
});

const HomeStack = createStackNavigator({
  Drawer: DrawerNavigator,
  Details: DetailsScreen,
  /* add routes here where you want the drawer to be locked */
});

const AppNavigator = createSwitchNavigator({
  Auth: AuthScreen,
  Home: HomeStack,
});
```

---

## Custom Android back button behavior

Source: https://reactnavigation.org/docs/4.x/custom-android-back-button-handling

By default, when user presses the Android hardware back button, react-navigation will pop a screen or exit the app if there are no screens to pop. This is a sensible default behavior, but there are situations when you might want to implement custom handling.

As an example, consider a screen where user is selecting items in a list, and a "selection mode" is active. On a back button press, you would first want the "selection mode" to be deactivated, and the screen should be popped only on the second back button press. The following code snippet demonstrates the situation. We make use of [`BackHandler`](https://reactnative.dev/docs/backhandler.html) which comes with react-native and add additional check (`navigation.isFocused()`) to make sure that our code only gets executed if the screen is focused.

Returning `true` from `onBackButtonPressAndroid` denotes that we have handled the event, and react-navigation's listener will not get called, thus not popping the screen. Returning `false` will cause the event to bubble up and react-navigation's listener will pop the screen.

```js
import React from 'react';
import { BackHandler } from 'react-native';

class ScreenWithCustomBackBehavior extends React.Component {
  componentDidMount() {
    BackHandler.addEventListener(
      'hardwareBackPress',
      this.handleBackButtonPressAndroid
    );
  }

  componentWillUnmount() {
    BackHandler.removeEventListener(
      'hardwareBackPress',
      this.handleBackButtonPressAndroid
    );
  }

  handleBackButtonPressAndroid = () => {
    if (!this.props.navigation.isFocused()) {
      // The screen is not focused, so don't do anything
      return false;
    }

    if (this.isSelectionModeEnabled()) {
      this.disableSelectionMode();

      // We have handled the back button
      // Return `true` to prevent react-navigation from handling it
      return true;
    } else {
      return false;
    }
  };

  render() {
    // ...
  }
}
```

The presented approach will work well for screens that are shown in a `StackNavigator`. Custom back button handling in other situations may not be supported at the moment (eg. A known case when this does not work is when you want to handle back button press in an open drawer. PRs for such use cases are welcome!).

---

## Access the navigation prop from any component

Source: https://reactnavigation.org/docs/4.x/connecting-navigation-prop

[`withNavigation`](with-navigation.md) is a higher order component which passes the `navigation` prop into a wrapped Component. It's useful when you cannot pass the `navigation` prop into the component directly, or don't want to pass it in case of a deeply nested child.

An ordinary component that is not a screen component will not receive the navigation prop by default, for example in this `MyBackButton` component:

```javascript
import React from 'react';
import { Button } from 'react-native';

export default class MyBackButton extends React.Component {
  render() {
    // This will throw an 'undefined is not a function' exception because the navigation
    // prop is undefined.
    return (
      <Button
        title="Back"
        onPress={() => {
          this.props.navigation.goBack();
        }}
      />
    );
  }
}
```

To resolve this exception, you could pass the `navigation` prop in to `MyBackButton` when you render it from a screen, like so: `<MyBackButton navigation={this.props.navigation} />`.

Alternatively, you can use the `withNavigation` function to provide the `navigation` prop automatically (through React context, if you're curious). This function behaves similarly to Redux's `connect` function, except rather than providing the `dispatch` prop to the component it wraps, it provides the `navigation` prop.

```js
import React from 'react';
import { Button } from 'react-native';
import { withNavigation } from 'react-navigation';

class MyBackButton extends React.Component {
  render() {
    return (
      <Button
        title="Back"
        onPress={() => {
          this.props.navigation.goBack();
        }}
      />
    );
  }
}

// withNavigation returns a component that wraps MyBackButton and passes in the
// navigation prop
export default withNavigation(MyBackButton);
```

Using this approach, you can render `MyBackButton` anywhere in your app without passing in a `navigation` prop explicitly and it will work as expected.

---

## Navigating without the navigation prop

Source: https://reactnavigation.org/docs/4.x/navigating-without-navigation-prop

Calling functions such as `navigate` or `popToTop` on the `navigation` prop is not the only way to navigate around your app. As an alternative, you can dispatch navigation actions on your top-level navigator, provided you aren't passing your own `navigation` prop as you would with a redux integration. The presented approach is useful in situations when you want to trigger a navigation action from places where you do not have access to the `navigation` prop, or if you're looking for an alternative to using the `navigation` prop.

You can get access to a navigator through a `ref` and pass it to the `NavigationService` which we will later use to navigate. Use this only with the top-level (root) navigator of your app.

```javascript
// App.js

import { createStackNavigator, createAppContainer } from 'react-navigation';
import NavigationService from './NavigationService';

const TopLevelNavigator = createStackNavigator({
  /* ... */
});

const AppContainer = createAppContainer(TopLevelNavigator);

export default class App extends React.Component {
  // ...

  render() {
    return (
      <AppContainer
        ref={(navigatorRef) => {
          NavigationService.setTopLevelNavigator(navigatorRef);
        }}
      />
    );
  }
}
```

In the next step, we define `NavigationService` which is a simple module with functions that dispatch user-defined navigation actions.

```javascript
// NavigationService.js

import { NavigationActions } from 'react-navigation';

let _navigator;

function setTopLevelNavigator(navigatorRef) {
  _navigator = navigatorRef;
}

function navigate(routeName, params) {
  _navigator.dispatch(
    NavigationActions.navigate({
      routeName,
      params,
    })
  );
}

// add other navigation functions that you need and export them

export default {
  navigate,
  setTopLevelNavigator,
};
```

Then, in any of your javascript modules, just import the `NavigationService` and call functions which you exported from it. You may use this approach outside of your React components and, in fact, it works just as well when used from within them.

```javascript
// any js module
import NavigationService from 'path-to-NavigationService.js';

// ...

NavigationService.navigate('ChatScreen', { userName: 'Lucy' });
```

In `NavigationService`, you can create your own navigation actions, or compose multiple navigation actions into one, and then easily reuse them throughout your application. When writing tests, you may mock the navigation functions, and make assertions on whether the correct functions are called, with the correct parameters.

---

## Using the navigation key

Source: https://reactnavigation.org/docs/4.x/navigation-key

The `key` parameter comes up repeatedly across different navigation functions. Let's take a look at a summary of its use cases:

### Usage with the [`navigate`](navigation-actions.md#navigate) call

If no key is provided, `StackRouter` will behave as follows:

- if a route with the given name already exists in the state, `StackRouter` will jump to the existing route, along with setting the new parameters.
- if no such route exists, `StackRouter` will push it onto the stack

If, however, you want to push several instances of the same route, you can do so by providing a unique `key` parameter each time you call `navigate`, or you can use the `push` action available on `StackRouter`. See the related [RFC](https://github.com/react-navigation/rfcs/blob/master/text/0004-less-pushy-navigate.md) for more background.

> Note: the behavior of `navigate` without a `key` is significantly different in the 1.x series of releases. Read more about it [here](https://gist.github.com/vonovak/ef72f5efe1d36742de8968ff6a708985).

### Usage with [`reset`](stack-actions.md#reset)

When resetting, `key` is also optional and can be a string or `null`. If set, the navigator with the given key will reset. If `null`, the root navigator will reset. You can obtain a route's navigator key by calling `this.props.navigation.dangerouslyGetParent().state.key`. Reason why the function is called `dangerouslyGetParent` is to warn developers against overusing it to eg. get parent of parent and other hard-to-follow patterns.

### Usage with [`replace`](stack-actions.md#replace)

With the `replace` navigation action, `key` is a required parameter used for identifying the route to be replaced. If you use the helper function `this.props.navigation.replace`, we will automatically substitute the key of the current route.

### Usage with `goBack`

Please refer to the [`goBack docs`](navigation-prop.md#goback---close-the-active-screen-and-move-back) for a detailed explanation.

---

## Deep linking

Source: https://reactnavigation.org/docs/4.x/deep-linking

In this guide we will set up our app to handle external URIs. Let's suppose that we want a URI like `example://chat/Eric` to open our app and link straight into a chat screen for some user named "Eric".

## Configuration

Previously, we had defined a navigator like this:

```js
const SimpleApp = createAppContainer(
  createStackNavigator({
    Home: { screen: HomeScreen },
    Chat: { screen: ChatScreen },
  })
);
```

We want paths like `chat/Eric` to link to a "Chat" screen with the `user` passed as a param. Let's re-configure our chat screen with a `path` that tells the router what relative path to match against, and what params to extract. This path spec would be `chat/:user`.

```js
const SimpleApp = createAppContainer(
  createStackNavigator({
    Home: { screen: HomeScreen },
    Chat: {
      screen: ChatScreen,
      path: 'chat/:user',
    },
  })
);
```

If we have nested navigators, we need to provide each parent screen with a `path`. All the paths will be concatenated and can also be an empty string. This path spec would be `friends/chat/:user`.

```js
const AuthSwitch = createAppContainer(
  createStackNavigator({
    AuthLoading: { screen: AuthLoadingScreen },
    App: {
      screen: AppStack,
      path: '',
    },
    Auth: { screen: AuthStack },
  })
);

const AppStack = createStackNavigator({
  Home: { screen: HomeScreen },
  Friends: {
    screen: FriendsScreen,
    path: 'friends',
  },
});

const FriendsScreen = createStackNavigator({
  Overview: { screen: OverviewScreen },
  Chat: {
    screen: ChatScreen,
    path: 'chat/:user',
  },
});
```

## Set up with Expo projects

First, you will want to specify a URL scheme for your app. This corresponds to the string before `://` in a URL, so if your scheme is `example` then a link to your app would be `example://`. The scheme only applies to standalone apps and you need to re-build the standalone app for the change to take effect. In the Expo client app you can deep link using `exp://ADDRESS:PORT` where `ADDRESS` is often `127.0.0.1` and `PORT` is often `19000` - the URL is printed when you run `expo start`. If you want to test with your custom scheme you will need to run `expo build:ios -t simulator` or `expo build:android` and install the resulting binaries in your emulators. You can register for a scheme in your `app.json` by adding a string under the scheme key:

```json
{
  "expo": {
    "scheme": "example"
  }
}
```

### URI Prefix

Next, let's configure our navigation container to extract the path from the app's incoming URI.

```js
// Install this package with `npx expo install expo-linking`
import * as Linking from 'expo-linking';

const SimpleApp = createAppContainer(createStackNavigator({...}));

// Linking.createURL is available as of expo@40.0.1 and expo-linking@2.0.1. If
// you are using older versions, you can upgrade or use Linking.makeUrl instead,
// but note that your deep links in standalone apps will be in the format
// scheme:/// rather than scheme:// if you use makeUrl.
const prefix = Linking.createURL('/');

const MainApp = () => <SimpleApp uriPrefix={prefix} />;
```

The reason that is necessary to use `Linking.createURL` is that the scheme will differ depending on whether you're in the client app or in a standalone app.

### Test deep linking on iOS

To test the URI on the simulator in the Expo client app, run the following:

```bash
xcrun simctl openurl booted [ put your URI prefix in here ]

// for example

xcrun simctl openurl booted exp://127.0.0.1:19000/--/chat/Eric
```

### Test deep linking on Android

To test the intent handling in the Expo client app on Android, run the following:

```bash
adb shell am start -W -a android.intent.action.VIEW -d "[ put your URI prefix in here ]" host.exp.exponent

# for example

adb shell am start -W -a android.intent.action.VIEW -d "exp://127.0.0.1:19000/--/chat/jane" host.exp.exponent
```

Change `host.exp.exponent` to your app package name if you are testig on a standalone app.

Read the [Expo linking guide](https://docs.expo.io/versions/latest/guides/linking.html) for more information about how to configure linking in projects built with Expo.

## Set up with `react-native init` projects

### URI Prefix

Next, let's configure our navigation container to extract the path from the app's incoming URI.

```js
const SimpleApp = createAppContainer(createStackNavigator({...}));

const prefix = 'example://';

const MainApp = () => <SimpleApp uriPrefix={prefix} />;
```

### iOS

Let's configure the native iOS app to open based on the `example://` URI scheme.

In `SimpleApp/ios/SimpleApp/AppDelegate.m`:

```bash
// Add the header at the top of the file:
#import <React/RCTLinkingManager.h>

// Add this above the `@end`:
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url
            options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
{
  return [RCTLinkingManager application:app openURL:url options:options];
}
```

In Xcode, open the project at `SimpleApp/ios/SimpleApp.xcodeproj`. Select the project in sidebar and navigate to the info tab. Scroll down to "URL Types" and add one. In the new URL type, set the identifier and the URL scheme to your desired URL scheme.

![Xcode project info URL types with example added](/assets/deep-linking/xcode-linking.png)

Now you can press play in Xcode, or re-build on the command line:

```bash
react-native run-ios
```

To test the URI on the simulator, run the following:

```bash
xcrun simctl openurl booted example://chat/Eric
```

To test the URI on a real device, open Safari and type `example://chat/Eric`.

### Android

To configure the external linking in Android, you can create a new intent in the manifest.

In `SimpleApp/android/app/src/main/AndroidManifest.xml`, do these followings adjustments:

1. Set `launchMode` of `MainActivity` to `singleTask` in order to receive intent on existing `MainActivity`. It is useful if you want to perform navigation using deep link you have been registered - [details](http://developer.android.com/training/app-indexing/deep-linking.html#adding-filters)
2. Add the new `intent-filter` inside the `MainActivity` entry with a `VIEW` type action:

```bash
<activity
    android:name=".MainActivity"
    android:launchMode="singleTask">
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="example" />
    </intent-filter>
</activity>
```

Now, re-install the app:

```bash
react-native run-android
```

To test the intent handling in Android, run the following:

```bash
adb shell am start -W -a android.intent.action.VIEW -d "example://chat/Eric" com.simpleapp
```

## Disable deep linking

In case you want to handle routing with deep-linking by yourself instead of `react-navigation`, you can pass `enableURLHandling={false}` prop to your app container:

```js
const SimpleApp = createAppContainer(createStackNavigator({...}));

const MainApp = () => <SimpleApp enableURLHandling={false} />;
```

Then, to handle the URL with the parameters, you can use `Linking` in your components to react to events.

```js
componentDidMount() {
    // [...]
    Linking.addEventListener('url', this.handleDeepLink)
}
componentWillUnmount() {
    // [...]
    Linking.removeEventListener('url', this.handleDeepLink);
}
```

And the method to handle it :

```js
handleDeepLink(e) {
    const route = e.url.replace(/.*?:\/\//g, '')
    // use route to navigate
    // ...
}
```

This should get you started! 🥳

---

## Screen tracking for analytics

Source: https://reactnavigation.org/docs/4.x/screen-tracking

This example shows how to do screen tracking and send to Google Analytics. The approach can be adapted to any other analytics SDK.

## Listening to State Changes

```js
import { createAppContainer, createStackNavigator } from 'react-navigation';
import analytics from '@react-native-firebase/analytics';

// gets the current screen from navigation state
function getActiveRouteName(navigationState) {
  if (!navigationState) {
    return null;
  }
  const route = navigationState.routes[navigationState.index];
  // dive into nested navigators
  if (route.routes) {
    return getActiveRouteName(route);
  }
  return route.routeName;
}

const AppNavigator = createStackNavigator(AppRouteConfigs);
const AppContainer = createAppContainer(AppNavigator);

export default () => (
  <AppContainer
    onNavigationStateChange={async (prevState, currentState) => {
      const currentRouteName = getActiveRouteName(currentState);
      const previousRouteName = getActiveRouteName(prevState);

      if (previousRouteName !== currentRouteName) {
        // the line below uses the @react-native-firebase/analytics tracker
        // change the tracker here to use other Mobile analytics SDK.
        await analytics().logScreenView({
          screen_name: currentRouteName,
          screen_class: currentRouteName,
        });
      }
    }}
  />
);
```

---

## Themes

Source: https://reactnavigation.org/docs/4.x/themes

Providing a light theme and a dark theme is a nice way to let your users adjust the appearance of your app depending on the time of day or their preference. It also signals that you are a hip app developer that keeps up with the trends of the day.

# Built-in themes

> Note: support for built-in themes requires react-navigation@>=3.12.0!

As operating systems add built-in support for light and dark modes, supporting dark mode is less about keeping hip to trends and more about conforming to the average user expectations for how apps should work. In order to provide support for light and dark mode in a way that is reasonably consistent with the OS defaults, these themes are built in to React Navigation. You can pass in a `theme` prop to your app container component in order to switch between light and dark mode, and the value of that `theme` prop can come from whichever API you use to detect user preferences for dark mode, or in the case of older operating system versions, from a custom configuration within your app UI.

```js
let Navigation = createAppContainer(RootStack);

// `theme` can be `light` or `dark`. It defaults to `light` if not specified.
export default () => <Navigation theme="light" />;
```

This will take care of styling the stack navigator, bottom tab navigator, and drawer navigator for you. React Navigation also provides several tools to help you make your customizations of those navigators and the screens within the navigators support both themes too.

## Using the operating system preferences

At the time of writing, `react-native` does not currently support detecting the operating system color scheme preferences in the core ([you can follow this pull request](https://github.com/facebook/react-native/pull/26172)). Until it is part of core and you have updated to the version that includes it, you can use `react-native-appearance`.

You will need iOS 13 to actually be able to toggle dark mode through system settings.

> Note: if you use the Expo managed workflow, this requires SDK 35+

First, you need to install `react-native-appearance`. [Follow the instructions in the README](https://github.com/expo/react-native-appearance).

Once you've installed it, set your root component up as follows:

```js
import { AppearanceProvider, useColorScheme } from 'react-native-appearance';

// Other navigation code goes here...
let Navigation = createAppContainer(RootStack);

export default () => {
  let theme = useColorScheme();

  return (
    <AppearanceProvider>
      <Navigation theme={theme} />
    </AppearanceProvider>
  );
};
```

If the version of React Native you are using doesn't support hooks yet, you can use the `Appearance.addChangeListener(cb)` and `Appearance.getColorScheme()` functions as described in the [usage section of the README](https://github.com/expo/react-native-appearance#usage).

See a full working example of theme integration in [react-navigation/theme-example](https://github.com/react-navigation/theme-example).

## Using the currently selected theme

Two tools are available to gain access to the theme in any component that descends from the app navigation container: `useTheme` and `ThemeContext`.

`useTheme` is a simple custom hook that returns the theme.

```js
import * as React from 'react';
import { TouchableOpacity, Text } from 'react-native';
import { useTheme } from 'react-navigation';

// Black background and white text in light theme, inverted on dark theme
function MyButton() {
  let theme = useTheme();

  return (
    <TouchableOpacity
      style={{ backgroundColor: theme === 'light' ? '#000' : '#fff' }}
    >
      <Text style={{ color: theme === 'light' ? '#fff' : '#000' }}>
        Button!
      </Text>
    </TouchableOpacity>
  );
}
```

`ThemeContext` lets you access the theme using the `ThemeContext.Consumer` pattern or with `static contextType`.

```js
import * as React from 'react';
import { TouchableOpacity, Text } from 'react-native';
import { ThemeContext } from 'react-navigation';

function MyButton() {
  return (
    <ThemeContext.Consumer>
      {(theme) => (
        <TouchableOpacity
          style={{ backgroundColor: theme === 'light' ? '#000' : '#fff' }}
        >
          <Text style={{ color: theme === 'light' ? '#fff' : '#000' }}>
            Button!
          </Text>
        </TouchableOpacity>
      )}
    </ThemeContext.Consumer>
  );
}
```

```js
import * as React from 'react';
import { TouchableOpacity, Text } from 'react-native';
import { ThemeContext } from 'react-navigation';

class MyButton extends React.Component {
  static contextType = ThemeContext;

  render() {
    const theme = this.context;
    return (
      <TouchableOpacity
        style={{ backgroundColor: theme === 'light' ? '#000' : '#fff' }}
      >
        <Text style={{ color: theme === 'light' ? '#fff' : '#000' }}>
          Button!
        </Text>
      </TouchableOpacity>
    );
  }
}
```

### Using default theme colors

There is a small but perhaps useful list of colors that are used to style navigators according to the theme. This list of colors is exported under `ThemeColors`. See the TypeScript definition for a full list of colors.

```js
import * as React from 'react';
import { TouchableOpacity, Text } from 'react-native';
import { ThemeColors, useTheme } from 'react-navigation';

function MyButton() {
  let theme = useTheme();
  let colors = ThemeColors[theme];

  return (
    <TouchableOpacity style={{ backgroundColor: colors.bodyContent }}>
      <Text style={{ color: colors.label }}>Button!</Text>
    </TouchableOpacity>
  );
}
```

### Default themed components

Several components have defaults that are biased to a specific theme. `Text`, for example, defaults to black. `StatusBar` defaults to dark text. React Navigation provides themed alternatives to these.

```js
import * as React from 'react';
import { TouchableOpacity, Text } from 'react-native';
import { Themed } from 'react-navigation';

function MyButton() {
  return (
    <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
      <TouchableOpacity style={{ backgroundColor: colors.bodyContent }}>
        <Themed.Text>Button!</Themed.Text>
      </TouchableOpacity>
      <Themed.StatusBar />
    </View>
  );
}
```

## Built-in themes inside `navigationOptions`

```jsx
import {
  ThemeColors,
  createAppContainer,
  createStackNavigator,
} from 'react-navigation';

class HomeScreen extends React.Component {
  static navigationOptions = ({ theme }) => {
    return {
      title: 'Home',
      headerLeft: () => (
        <Button
          color={theme === 'dark' ? 'white' : 'blue'}
          title="Press me"
          onPress={() => alert('success!')}
        />
      ),
    };
  };

  render() {
    // etc...
  }
}
```

## Built-in themes inside static navigator configuration

Colors that are specified within the static configuration options for a navigator can now be specified as objects with `light` and `dark` keys:

```js
let Tabs = createBottomTabNavigator(
  {
    /* routes */
  },
  {
    tabBarOptions: {
      activeTintColor: {
        light: '#000',
        dark: '#fff',
      },
      inactiveTintColor: {
        light: 'rgba(0,0,0,0.2)',
        dark: 'rgba(255,255,255,0.2)',
      },
    },
  }
);
```

The old format still works too, but colors specified in the following way will not adapt to themes:

```js
let Tabs = createBottomTabNavigator(
  {
    /* routes */
  },
  {
    tabBarOptions: {
      activeTintColor: '#000',
      inactiveTintColor: 'rgba(0,0,0,0.2)',
    },
  }
);
```

# Custom themes using React context

You may want more control than what you're given with just the built-in themes. In this case, you can build your own themes entirely from scratch.

Building custom themes into an app with React Navigation is not too much different than a React app without it; the main differences are that you will need to use `screenProps` in order to update style properties controlled by `navigationOptions`, and when style properties are controlled in navigator configuration we'll need to take another approach. First we're going to recap how you would theme a React app without React Navigation, then we will dive deeper into these differences. Additionally, this guide assumes that you are already comfortable with React Navigation, in particular how to use and configure navigators.

React's context API allows you to share state from an ancestor component to any of its descendants without explicitly passing the value through layers and layers of components ("prop drilling"). This is a useful tool in order to build themes because we can define the theme at the root of the app, and then access it from anywhere else and re-render every themed component whenever the theme changes. If you are not familiar with how to use context already, you might want to read the [React documentation](https://reactjs.org/docs/context.html) for it before continuing.

```jsx
import * as React from 'react';
import { Text, TouchableOpacity, View } from 'react-native';

const ThemeContext = React.createContext(null);
const ThemeConstants = {
  light: {
    backgroundColor: '#fff',
    fontColor: '#000',
  },
  dark: {
    backgroundColor: '#000',
    fontColor: '#fff',
  },
};

export default class AppContainer extends React.Component {
  state = {
    theme: 'light',
  };

  toggleTheme = () => {
    this.setState(({ theme }) => ({
      theme: theme === 'light' ? 'dark' : 'light',
    }));
  };

  render() {
    return (
      <ThemeContext.Provider
        value={{ theme: this.state.theme, toggleTheme: this.toggleTheme }}
      >
        <HomeScreen />
      </ThemeContext.Provider>
    );
  }
}

class HomeScreen extends React.Component {
  render() {
    return (
      <ThemedView
        style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}
      >
        <ThemeContext.Consumer>
          {({ toggleTheme }) => (
            <ThemedButton title="Toggle theme" onPress={toggleTheme} />
          )}
        </ThemeContext.Consumer>
      </ThemedView>
    );
  }
}

class ThemedButton extends React.Component {
  render() {
    let { title, ...props } = this.props;
    return (
      <TouchableOpacity {...props}>
        <ThemeContext.Consumer>
          {({ theme }) => (
            <Text style={{ color: ThemeConstants[theme].fontColor }}>
              {title}
            </Text>
          )}
        </ThemeContext.Consumer>
      </TouchableOpacity>
    );
  }
}

class ThemedView extends React.Component {
  render() {
    return (
      <ThemeContext.Consumer>
        {({ theme }) => (
          <View
            {...this.props}
            style={[
              this.props.style,
              { backgroundColor: ThemeConstants[theme].backgroundColor },
            ]}
          />
        )}
      </ThemeContext.Consumer>
    );
  }
}
```

Okay, that's a lot of code. There isn't much going on here aside from passing the theme around through context and then pulling it out of context when we need it inside of themed component. Themed components like `ThemedView` and `ThemedButton` are useful to help you avoid constantly repeating theme context related boilerplate.

## Themes inside `navigationOptions`

A regrettable limitation of the current implementation of `navigationOptions` is that we are unable to access React context for use in properties such as `headerStyle` and `headerTintColor`. We can and should use them in properties that access React components, for example in `headerRight` we could provide a component like `ThemedHeaderButton`. To apply the theme to other properties we need to use `screenProps`.

```jsx
import {
  createAppContainer,
  createStackNavigator,
  ThemeContext,
} from 'react-navigation';

class HomeScreen extends React.Component {
  static navigationOptions = ({ screenProps }) => {
    let currentTheme = ThemeConstants[screenProps.theme];

    return {
      title: 'Home',
      headerTintColor: currentTheme.fontColor,
      headerStyle: { backgroundColor: currentTheme.backgroundColor },
    };
  };

  render() {
    return (
      <ThemedView
        style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}
      >
        <ThemeContext.Consumer>
          {({ toggleTheme }) => (
            <ThemedButton title="Toggle theme" onPress={toggleTheme} />
          )}
        </ThemeContext.Consumer>
      </ThemedView>
    );
  }
}

const Stack = createStackNavigator({ Home: HomeScreen });
const Navigation = createAppContainer(Stack);

export default class AppContainer extends React.Component {
  state = {
    theme: 'light',
  };

  toggleTheme = () => {
    this.setState(({ theme }) => ({
      theme: theme === 'light' ? 'dark' : 'light',
    }));
  };

  render() {
    return (
      <ThemeContext.Provider
        value={{ theme: this.state.theme, toggleTheme: this.toggleTheme }}
      >
        <Navigation screenProps={{ theme: this.state.theme }} />
      </ThemeContext.Provider>
    );
  }
}
```

Success! The stack header style now updates when the theme changes.

> Note: in the future we would like to deprecate `screenProps` and move entirely over to React context. For now, `screenProps` is the best way to do that, and when this changes it will be easy to migrate.

## Theming tabs and other similar navigators

Some navigators may have their styles configured in the navigator configuration object when they are initialized. While it may be best to update these navigators so that they can be configured more easily through `navigationOptions`, as long as they allow us to override the UI that they render with our own component and give us access to the default component, we can work with them just fine. We'll look at how to theme a bottom tab navigator.

```jsx
import {
  createAppContainer,
  createStackNavigator,
  createBottomTabNavigator,
  BottomTabBar,
  ThemeContext,
} from 'react-navigation';

const ThemeConstants = {
  light: {
    backgroundColor: '#fff',
    fontColor: '#000',
    activeTintColor: 'blue',
    inactiveTintColor: '#ccc',
  },
  dark: {
    backgroundColor: '#000',
    fontColor: '#fff',
    activeTintColor: '#fff',
    inactiveTintColor: '#888',
  },
};

// Notice how we override the `activeTintColor`, `inactiveTintColor` and
// `backgroundColor` of the tab bar with our theme styles.
class ThemedBottomTabBar extends React.Component {
  render() {
    return (
      <ThemeContext.Consumer>
        {({ theme }) => (
          <BottomTabBar
            {...this.props}
            activeTintColor={ThemeConstants[theme].activeTintColor}
            inactiveTintColor={ThemeConstants[theme].inactiveTintColor}
            style={{
              backgroundColor: ThemeConstants[theme].backgroundColor,
            }}
          />
        )}
      </ThemeContext.Consumer>
    );
  }
}

const Stack = createStackNavigator({ Home: HomeScreen });
const Tabs = createBottomTabNavigator(
  { Stack },
  { tabBarComponent: ThemedBottomTabBar }
);
const Navigation = createAppContainer(Tabs);

// And the rest of the code goes here...
```

You will likely want to go a bit further than we detailed in this guide, such as change the status bar color depending on the theme and customize the border color for the header and tab bar as well. You can see all of the above code plus some more changes to make it more complete in [this Snack](https://snack.expo.io/@react-navigation/themes-example).

I never said it was easy, but this about covers what you need to know to be able to theme an app that uses React Navigation. Good luck, remember me when you're a billionaire.

---

## State persistence

Source: https://reactnavigation.org/docs/4.x/state-persistence

You may want to save the user's location in the app, so that they are immediately returned to the same location after the app is restarted.

This is especially valuable during development because it allows the developer to stay on the same screen when they refresh the app.

> Note: This feature is currently considered experimental, because of the warnings listed at the end of this page. Use with caution!

## Usage

You can enable persistence for your top-level navigator by rendering it with `persistNavigationState` and `loadNavigationState` props:

- `persistNavigationState` is an async function that receives single argument - the navigation state object. The function should persist it.
- `loadNavigationState` is an async function that does the inverse - it should load the persisted navigation state and return a Promise that resolves with the navigation state object. If the function rejects, React Navigation will start as if no state was provided.

```js
const AppNavigator = createStackNavigator({...});
const persistenceKey = "persistenceKey"
const persistNavigationState = async (navState) => {
  try {
    await AsyncStorage.setItem(persistenceKey, JSON.stringify(navState))
  } catch(err) {
    // handle the error according to your needs
  }
}
const loadNavigationState = async () => {
  const jsonString = await AsyncStorage.getItem(persistenceKey)
  return JSON.parse(jsonString)
}

const App = () => <AppNavigator persistNavigationState={persistNavigationState} loadNavigationState={loadNavigationState} />;
```

### Development Mode

This feature is particularly useful in development mode. You can enable it selectively using the following approach:

```js
const AppNavigator = createStackNavigator({...});
function getPersistenceFunctions() {
  return __DEV__ ? {
    persistNavigationState: ...,
    loadNavigationState: ...,
  } : undefined;
}
const App = () => <AppNavigator {...getPersistenceFunctions()} />;
```

### Loading View

Because the state is loaded asynchronously, the app must render an empty/loading view for a moment before the `loadNavigationState` function returns. To customize the loading view that is rendered during this time, you can use the `renderLoadingExperimental` prop:

```js
<AppNavigator
  persistNavigationState={...}
  loadNavigationState={...}
  renderLoadingExperimental={() => <ActivityIndicator />}
/>
```

> Note: This API may change in the future, which is why it is labeled experimental

## Warning: Serializable State

Each param, route, and navigation state must be fully serializable for this feature to work. Typically, you would serialize the state as a JSON string. This means that your routes and params must contain no functions, class instances, or recursive data structures.

If you need to modify the nav state object, you may do so in the `loadNavigationState` / `persistNavigationState` functions, but note that if your `loadNavigationState` provides an invalid object (an object from which the navigation state cannot be recovered), React Navigation may not be able to handle the situation gracefully.

## Warning: Route/Router definition changes

When your application code changes to support new routes or different routers for a given route in your navigation state, the app may break when presented with the old navigation state.

This may happen regularly during development as you re-configure your routes and navigator hierarchy. But it also may happen in production when you release a new version of your app!

The conservative behavior is to wipe the navigation state when the app has been updated. The easiest way to do this is to refer to a different persistence key for each version that you release to users.

React Navigation uses React's `componentDidCatch` functionality to attempt to mitigate crashes caused by route definition changes, but this is considered experimental and may not catch all errors.

---

## Type checking with TypeScript

Source: https://reactnavigation.org/docs/4.x/typescript

React Navigation exports type definitions for TypeScript projects, which can be used to type check screens, navigation options, and the navigation prop.

### Type checking `navigation` prop

The `navigation` prop can be annotated to provide type checking for params and basic type checking for the available methods.

The type depends on the navigator that renders the screen. For example, the `navigation` prop provided by `createStackNavigator` can be used like:

```tsx
import { NavigationStackProp } from 'react-navigation-stack';

type Props = {
  navigation: NavigationStackProp<{ userId: string }>;
};

class ProfileScreen extends React.Component<Props> {
  // ...
}
```

The types take a generic for the params object.

Along with `NavigationStackProp`, each navigator exports its own type for navigation prop:

- `NavigationStackProp` for `createStackNavigator` from `react-navigation-stack`
- `NavigationTabProp` for `createBottomTabNavigator` and `createMaterialTopTabNavigator` from `react-navigation-tabs`
- `NavigationDrawerProp` for `createDrawerNavigator` from `react-navigation-drawer`

### Type checking all props for a screen

A screen receives the `theme` and `screenProps` props along with the `navigation` prop. Instead of needing to annotate each property, they can be consolidated.

The type depends on the navigator that renders the screen. For example, for a screen in `createStackNavigator`:

```tsx
import { NavigationStackScreenProps } from 'react-navigation-stack';

type Params = { userId: string };

type ScreenProps = { language: string };

class ProfileScreen extends React.Component<
  NavigationStackScreenProps<Params, ScreenProps>
> {
  // ...
}
```

The `Params` and `ScreenProps` generics are optional, and can be omitted if you're not using them.

Along with `NavigationStackScreenProps`, each navigator exports its own type for navigation prop:

- `NavigationStackScreenProps` for `createStackNavigator` from `react-navigation-stack`
- `NavigationTabScreenProps` for `createBottomTabNavigator` and `createMaterialTopTabNavigator` from `react-navigation-tabs`
- `NavigationDrawerScreenProps` for `createDrawerNavigator` from `react-navigation-drawer`

### Type checking `navigationOptions`

Different navigators accept different set of options for the screen. They are specified in the `navigationOptions` static property which can be annotated to provide type-checking:

```tsx
import { NavigationStackOptions } from 'react-navigation-stack';

// ...

class ProfileScreen extends React.Component<Props> {
  static navigationOptions: NavigationStackOptions = {
    headerTitle: 'Profile',
  };

  // ...
}
```

Along with `NavigationStackOptions`, each navigator exports its own type for navigation prop:

- `NavigationStackOptions` for `createStackNavigator` from `react-navigation-stack`
- `NavigationBottomTabOptions` for `createBottomTabNavigator` from `react-navigation-tabs`
- `NavigationMaterialTabOptions` for `createMaterialTopTabNavigator` from `react-navigation-tabs`
- `NavigationDrawerOptions` for `createDrawerNavigator` from `react-navigation-drawer`

### Type checking screen components

Screens can be annotated to provide type-checking for the props it receives, as well as `navigationOptions` in a single type annotation.

The type depends on the navigator that renders the screen. For example, for a screen in `createStackNavigator`:

```tsx
import { NavigationStackScreenComponent } from 'react-navigation-stack';

type Params = { userId: string };

type ScreenProps = { language: string };

const ProfileScreen: NavigationStackScreenComponent<Params, ScreenProps> = (
  props
) => {
  // ...
};

ProfileScreen.navigationOptions = {
  headerTitle: 'Profile',
};
```

The `Params` and `ScreenProps` generics are optional, and can be omitted if you're not using them.

Along with `NavigationStackScreenComponent`, each navigator exports its own type for navigation prop:

- `NavigationStackScreenComponent` for `createStackNavigator` from `react-navigation-stack`
- `NavigationBottomTabScreenComponent` for `createBottomTabNavigator` from `react-navigation-tabs`
- `NavigationMaterialTabScreenComponent` for `createMaterialTopTabNavigator` from `react-navigation-tabs`
- `NavigationDrawerScreenComponent` for `createDrawerNavigator` from `react-navigation-drawer`

---

## Redux integration

Source: https://reactnavigation.org/docs/4.x/redux-integration

It is extremely easy to use Redux in an app with React Navigation. It's basically no different than without React Navigation. The following example shows how to do it end to end: [snack.expo.io/@react-navigation/redux-example](https://snack.expo.io/@react-navigation/redux-example). The most important piece from it is the following:

```js
let RootStack = createStackNavigator({
  Counter: CounterContainer,
  StaticCounter: StaticCounterContainer,
});

let Navigation = createAppContainer(RootStack);

// Render the app container component with the provider around it
export default class App extends React.Component {
  render() {
    return (
      <Provider store={store}>
        <Navigation />
      </Provider>
    );
  }
}
```

Notice that we take the component returned from `createAppContainer` and wrap it in a `Provider`. Ta da! Now feel free to use `connect` throughout your app.

## What about `navigationOptions`?

Alright fair enough, the answer here isn't the most obvious. Let's say that you want to access the Redux store state from the title, what would you do? There are a couple of options. For these examples let's say that you want to put the count from the above example into the title.

### Use a component that is `connect`ed

Create a component, `connect` it to the store, then use that component in the `title`.

```js
class Count extends React.Component {
  render() {
    return <Text>Count: {this.props.value}</Text>;
  }
}

let CountContainer = connect((state) => ({ value: state.count }))(Count);

class Counter extends React.Component {
  static navigationOptions = {
    title: <CountContainer />,
  };

  /* .. the rest of the code */
}
```

[See a runnable example](https://snack.expo.io/@react-navigation/redux-example-with-dynamic-title).

### Pass the state you care about as a param to the screen

If the value isn't expected to change, you can just pass it from a `connect`ed component to the other screen as a param.

```js
<Button
  title="Go to static count screen"
  onPress={() =>
    this.props.navigation.navigate('StaticCounter', {
      count: this.props.count,
    })
  }
/>
```

```js
class StaticCounter extends React.Component {
  static navigationOptions = ({ navigation }) => ({
    title: navigation.getParam('count'),
  });

  render() {
    return (
      <View style={styles.container}>
        <Text style={styles.paragraph}>
          {this.props.navigation.getParam('count')}
        </Text>
      </View>
    );
  }
}
```

[See a runnable example](https://snack.expo.io/@react-navigation/redux-example-with-dynamic-title).

### setParams from your screen

Let's modify the `StaticCounter` from the previous example as follows:

```js
class StaticCounter extends React.Component {
  static navigationOptions = ({ navigation }) => ({
    title: navigation.getParam('count'),
  });

  componentDidMount() {
    this.updateCount();
  }

  componentDidUpdate() {
    this.updateCount();
  }

  updateCount() {
    this.props.navigation.setParams({ count: this.props.count });
  }

  render() {
    return (
      <View style={styles.container}>
        <Text style={styles.paragraph}>
          {this.props.navigation.getParam('count')}
        </Text>
      </View>
    );
  }
}
```

Now whenever the store updates we update the `count` param and the title updates accordingly.

## Can I store the navigation state in Redux too?

This is technically possible, but we don't recommend it - it's too easy to shoot yourself in the foot and slow down / break your app. We encourage you to leave it up to React Navigation to manage the navigation state. But if you really want to do this, you can use [react-navigation-redux-helpers](https://github.com/react-navigation/react-navigation-redux-helpers), but this isn't an officially supported workflow.

---

## Integrating with MobX State Tree

Source: https://reactnavigation.org/docs/4.x/MST-integration

This guide explores possible way to use React Navigation in a React Native project that uses [MobX State Tree](https://github.com/mobxjs/mobx-state-tree)(MST) for state management. The guide is accompanied by a [sample app](https://github.com/vonovak/react-navigation-mst-demo). Parts of the guide may be relevant also for users of [MobX](https://github.com/mobxjs/mobx) but please be aware of the fact that MobX does not come with a built-in solution for (de)serializing its state.

> Please note that in this guide, Mobx State Tree is not used to manage the navigation state itself - just the navigation params!

## Overview

Our goal with this guide is to use MST with React Navigation and achieve optimal developer experience. In the scope of this guide, this means allowing us to do a full JS reload and be brought back to the state before the reload happened.

We will do this by persisting the navigation state using the React Navigation's [built-in mechanism](state-persistence.md). We also need to persist the app state and navigation params - that way, when you're working on a screen in your app and do a full JS reload, you will be brought back to the same screen, with the same data in it.

## Guide

First, start by creating initial navigation structure and React components. When you're done with that, continue with modelling your state in MST. If you want to learn more about this, check out the [egghead.io course](https://egghead.io/lessons/react-describe-your-application-domain-using-mobx-state-tree-mst-models).

At this point, you're probably wondering how to connect your MST objects with the components. The answer is in the [mobx-react package](https://github.com/mobxjs/mobx-react) that contains React bindings for MobX (they also work for MST). You will likely be using the `Provider` component and the `inject` and `observer` functions.

Use `Provider` to wrap what you return from your root component's render method:

```js
<Provider myObject={this.myObject}>
  <AppNavigator />
</Provider>
```

this will allow you to access `myObject` from any React component in the application through the `inject` function which can be quite useful.

Use `observer` function to wrap all components that render observable data. This will make sure the components re-render once the data they render changes.

### Navigation params

Screens in your application often depend on params. React Navigation allows you to [send params](params.md) from one screen to another. These params are stored in the navigation state. However, in order to persist the navigation state, it needs to be serializable. This requirement does not play well with MST, because the MST objects are complex objects and React Navigation doesn't know how to (de)serialize them. In this guide, we will work around this by storing the navigation params ourselves.

This means that rather than sending the params from one screen to another (eg. with `props.navigation.navigate('MyScreen', { complexMSTObject })`) we will store the params to a navigation store, then navigate without sending any params, and on the target screen, we'll pick the params up from the navigation store.

To give an example, the navigation store may look similar to this:

```js
import { types, onSnapshot, getRoot } from 'mobx-state-tree';
import { Product } from '../models/Product';
import { User } from '../models/User';

export const NavigationStore = types
  .model('NavigationStore', {
    productDetailScreenParams: types.map(
      types.model('ProductDetailScreenParams', {
        product: types.optional(types.safeReference(Product)),
      })
    ),
    userProfileScreenParams: types.model('UserProfileScreenParams', {
      user: types.maybe(types.safeReference(User)),
    }),
  })
  .actions(self => ({
    ...
  }));
```

Note that `userProfileScreenParams` is a simple model with a `user` entry, while `productDetailScreenParams` is a map of `ProductDetailScreenParams` model. The reason we chose this shape of data is that we only have a single user profile screen in our app which reads its params from `userProfileScreenParams`. `productDetailScreenParams` is a map because the app can have several product screens on a stack. Each screen points to a `Product` instance saved in the map. The keys into the map are the React Navigation [keys](navigation-key.md#usage-with-the-navigate-call): think of the `key` as of an identifier of the route.

Your navigation store may also be just one map where for each screen (regardless if it is a product or user profile screen), we store its navigation params. This is the approach taken in the [sample app](https://github.com/vonovak/react-navigation-mst-demo).

## Summary

- you can use React Navigation with MobX State Tree in a React Native app
- use the `Provider` component and the `inject` and `observer` functions to wire up MobX or MST with React
- it's possible to persist the entire application state and restore it upon JS reload

---

## Localization

Source: https://reactnavigation.org/docs/4.x/localization

English is only one of many languages people speak around the world (thanks a lot, [Tower of Babel](https://en.wikipedia.org/wiki/Tower_of_Babel)) and it's polite and sometimes even necessary to translate our app to the languages our users speak. Let's look at one way we can do this in React Navigation - it's not the only way but it'll do the trick. Similar to [themes](themes.md), we will use `screenProps`. You may also want to use React's context API as demonstrated in the [themes](themes.md) guide in order to make it easier to access the translate function from a variety of components.

## Setting up a localization library

We'll need to use some kind of library to store our translations and provide a function that gives us access to them, along with handling fallbacks when we don't have a particular language defined. Localization and internationalization (i18n) are often used interchangeably, as in the example below where we get the current `locale` from `expo-localization` and use the `i18n-js` library for managing translations, for no particular reason other than it was available - use whatever you like.

```jsx
import * as Localization from 'expo-localization'; // or whatever library you want
import i18n from 'i18n-js'; // or whatever library you want

const en = {
  foo: 'Foo',
  bar: 'Bar {{someValue}}',
};

const fr = {
  foo: 'Fou',
  bar: 'Bár {{someValue}}',
};

i18n.fallbacks = true;
i18n.translations = { fr, en };

// This will log 'en' for me, as I'm an English speaker
console.log(Localization.locale);
```

## Wiring up your localization library to navigation

Next let's store our `locale` in the state of our root app component and then thread it through `screenProps` to make it available throughout React Navigation.

```jsx
export default class App extends React.Component {
  state = {
    locale: Localization.locale,
  };

  setLocale = (locale) => {
    this.setState({ locale });
  };

  t = (scope, options) => {
    return i18n.t(scope, { locale: this.state.locale, ...options });
  };

  render() {
    return (
      <AppContainer
        screenProps={{
          t: this.t,
          locale: this.state.locale,
          setLocale: this.setLocale,
        }}
      />
    );
  }
}
```

Now in our screens we can use these `screenProps` as follows:

```jsx
class Screen extends React.Component {
  static navigationOptions = ({ screenProps: { t } }) => ({
    title: t('foo'),
  });

  render() {
    let { t, locale } = this.props.screenProps;

    return (
      <View style={styles.container}>
        <Text style={styles.text}>
          Current locale: {locale}.{' '}
          {locale !== 'en' && locale !== 'fr'
            ? 'Translations will fall back to "en" because none available'
            : null}
        </Text>
        <Text>{t('bar', { someValue: Date.now() })}</Text>
        {locale === 'en' ? (
          <Button
            title="Switch to French"
            onPress={() => this.props.screenProps.setLocale('fr')}
          />
        ) : (
          <Button
            title="Switch to English"
            onPress={() => this.props.screenProps.setLocale('en')}
          />
        )}
      </View>
    );
  }
}
```

You can run this example in [this Snack](https://snack.expo.io/@react-navigation/localization-example). Again, you may want to go further than just passing this through `screenProps` if you want to make it easier to access the `t` function or the other `screenProps` from any React component (and not just screen components that are rendered by React Navigation). Refer to [themes](themes.md) and the [React documentation on context](https://reactjs.org/docs/context.html) for help with that.

---

## React Navigation on the Web

Source: https://reactnavigation.org/docs/4.x/web-support

> Note: starting in v3, React Navigation has built-in support for use in web sites, including server rendering. This has not yet been widely used in production and we consider this feature to be experimental.

# With react-native-web

> "[React Native for Web](https://github.com/necolas/react-native-web)" makes it possible to run React Native components and APIs on the web using React DOM.

This approach allows you to reuse most of React Navigation on the web because React Native for Web maps React Native primitives like `View`, `Text`, and others to their equivalents on the web.

The easiest way to get started with this approach is to use to use the [Expo CLI web support beta](https://blog.expo.io/expo-cli-and-sdk-web-support-beta-d0c588221375). More information on how to set this up in other projects will follow in the future, help on documenting it is also welcome!

# With standard web tools

This approach requires that you rebuild the navigation views for your app (at least until the community builds out an alternative), but allows you to leverage routers and simple navigators that don't require views, like the switch navigator.

To set up a navigator in a React app, [(such as one created with create-react-app)](https://github.com/react-navigation/example-web):

```js
import { createSwitchNavigator } from '@react-navigation/core';
import { createBrowserApp } from '@react-navigation/web';

const MyNavigator = createSwitchNavigator(routes);

const App = createBrowserApp(MyNavigator);

// now you can render "App" normally
```

## Web Links

We ship a utility out of the box which automatically sets up an `<a>` tag for you with the correct `href`.

This is necessary to properly support server rendering, critical for accessibility, and nice to provide a good user experience when the browser displays what URL the link will go to.

When the app is running, the default browser behavior will be blocked and a navigation action will be dispatched instead.

To render a link to the "Profile" route:

```js
<Link toRoute="Profile" params={{ name: 'jamie' }}>
  Jamie's Profile
</Link>
```

Depending on the `path` that is set up for the `Profile` route, the above link may render to html as `<a href="/people/jamie">Jamie's Profile</a>`

You can alternatively provide an `action` prop to the `Link`, to specify the exact navigation action that will be used to handle this link.

## Server rendering

You can use the `handleServerRequest` function to get the top-level navigation prop for your app, as well as the current title for this route.

```js
expressApp.get('/*', (req, res) => {
  const { path, query } = req;

  const { navigation, title, options } = handleServerRequest(
    AppNavigator.router,
    path,
    query
  );

  const markup = renderToString(<AppNavigator navigation={navigation} />);

  res.send(
    `<!doctype html>
  <html lang="">
  <head>
    <title>${title}</title>
    <script src="main.js"></script>
  </head>
  <body>
    <div id="root">${markup}</div>
  </body>
</html>`
  );
});
```

For a full example, [see a full server+client React web app here](https://github.com/react-navigation/web-server-example)

## Custom navigators for the web

The built-in navigator components such as Stack are often not well suited for web sites, so you may want to create custom navigators yourself.

Your view can use `props.descriptors` to see the current set of screens, get their navigation object, and see the current navigation options. You should use `SceneView` to present your child screen components.

See ["Custom Navigators"](custom-navigators.md) for more details.

For an example of this, see how the custom `SidebarView` and `AppView` are used from [`App.js` in the web server example](https://github.com/react-navigation/web-server-example/blob/master/src/App.js).

---

## Call a function when focused screen changes

Source: https://reactnavigation.org/docs/4.x/function-after-focusing-screen

In this guide we will call a function on screen focusing. This is useful for making additional API calls when a user revisits a particular screen in a Tab Navigator, or to track user events as they tap around our app.

There are two approaches available to us:

1. Using the `withNavigationFocus` higher order component provided by react-navigation.
2. Listening to the `'didFocus'` event with an event listener.

## Triggering an action with the `withNavigationFocus` higher order component

react-navigation provides a [higher order component](https://reactjs.org/docs/higher-order-components.html) that passes an `isFocused` prop to our component, along with the `navigation` object we'd normally get with `withNavigation`.

When the `isFocused` prop is passed to our component, it will pass `true` when the screen is focused and `false` when our component is no longer focused. This enables us to call actions on a user entering or leaving a screen. This is particularly handy when we are trying to stop something when the page is unfocused, like stopping a video or audio file from playing, or stopping the tracking of a user's location.

Since `withNavigationFocus` passes a prop on every focus change, it will cause our component to re-render when we focus and unfocus a screen. Using this higher order component may introduce unnecessary component re-renders as a screen comes in and out of focus. This could cause issues depending on the type of action we're calling on focusing.

For instance, if we are attempting to make an API call on focus to fetch some data, we only want to fetch data when the component is focused and not when the component becomes unfocused. To prevent extra component re-renders, we could write some logic in `shouldComponentUpdate` to control when the component renders itself, however we may be better off using the event listener method detailed below. The event listener will only call an action and render the component when the screen is focused and will do nothing when a screen becomes unfocused.

### Example

```js
import React, { Component } from 'react';
import { View } from 'react-native';
import { withNavigationFocus } from 'react-navigation';

class TabScreen extends Component {
  componentDidUpdate(prevProps) {
    if (prevProps.isFocused !== this.props.isFocused) {
      // Use the `this.props.isFocused` boolean
      // Call any action
    }
  }

  render() {
    return <View />;
  }
}

// withNavigationFocus returns a component that wraps TabScreen and passes
// in the navigation prop
export default withNavigationFocus(TabScreen);
```

This example is also documented in the [`withNavigationFocus` API documentation](with-navigation-focus.md).

## Triggering an action with a `'didFocus'` event listener

We can also listen to the `'didFocus'` event with an event listener. After setting up an event listener, we must also stop listening to the event when the screen is unmounted.

With this approach, we will only be able to call an action when the screen focuses. This is great for fetching data with an API call when a screen becomes focused, or any other action that needs to happen once the screen comes into view.

### Example

```js
import React, { Component } from 'react';
import { View } from 'react-native';
import { withNavigation } from 'react-navigation';

class TabScreen extends Component {
  componentDidMount() {
    const { navigation } = this.props;
    this.focusListener = navigation.addListener('didFocus', () => {
      // The screen is focused
      // Call any action
    });
  }

  componentWillUnmount() {
    // Remove the event listener
    this.focusListener.remove();
  }

  render() {
    return <View />;
  }
}

export default withNavigation(TabScreen);
```

---

## Optimize memory usage and performance

Source: https://reactnavigation.org/docs/4.x/react-native-screens

Prior to `react-navigation@2.14.0`, all screens are essentially regular native `View` in each platform, which will increase memory usage and make the render tree deep in a heavy-stacked application. This is one of the reason your app is slowing down comparing to native navigation solution.

With the advent of `react-native-screens`, the native screen optimization is brought possible to `react-navigation` by bringing the native navigation component (`UIViewController` for iOS, and `FragmentActivity` for Android). By using `react-native-screens`, it is possible for each native platform to optimize the memory usage for screens that are under the view stack and also simplify the native node hierarchy. You can take a look at the comparison [here](https://twitter.com/janicduplessis/status/1039979591815897088?s=21) to see the performance gain.

## Setup when you are using Expo

By default expo already included `react-native-screens`, all you need to do is pasting the following snippet before your navigation stacks are rendered (typically in an `index.js` or `App.js` file):

```js
// Before rendering any navigation stack
import { useScreens } from 'react-native-screens';
useScreens();
```

## Setup in normal react-native applications

You will need to follow the installation instruction from [react-native-screens](https://github.com/software-mansion/react-native-screens) first. After that, you can import the library like mentioned above and enjoy the optimization.

---

## Upgrading from 3.x

Source: https://reactnavigation.org/docs/4.x/upgrading-from-3.x

In React Navigation 4, we've extracted out the navigators to separate packages to make it easier to maintain and release updates faster. You can follow the guide below to upgrade your projects.

> Note: Before making these changes, we recommend you to commit all local changes to git so you can revert back to a good state if something goes wrong with the upgrade.

## Install the new packages

First, we need to install the `react-navigation` package along with the various navigators. If you don't use some of these navigators, you can omit them.

To install them, run:

```bash npm2yarn
npm install react-navigation react-navigation-stack@^1.7.3 react-navigation-tabs@^1.2.0 react-navigation-drawer@^1.4.0
```

This will install the versions compatible with your code if you were using `react-navigation@3.x`, so you wouldn't need any more changes beyond changing the imports.

> Note: If you have `@react-navigation/core` or `@react-navigation/native` in your `package.json`, please remove them and change the imports to import from `react-navigation` package instead.

## Changing your code

Then change any imports for stack, tabs or drawer to import from the above packages instead of `react-navigation`.

```diff
- import { createAppContainer, createStackNavigator } from 'react-navigation';
+ import { createAppContainer } from 'react-navigation';
+ import { createStackNavigator } from 'react-navigation-stack';
```

The following imports need to be changed to import from `react-navigation-stack`:

- `createStackNavigator`
- `StackGestureContext`
- `Transitioner`
- `StackView`
- `StackViewCard`
- `StackViewTransitionConfigs`
- `Header`
- `HeaderTitle`
- `HeaderBackButton`
- `HeaderStyleInterpolator`

The following imports need to be changed to import from `react-navigation-tabs`:

- `createBottomTabNavigator`
- `createMaterialTopTabNavigator`
- `BottomTabBar`
- `MaterialTopTabBar`

The following imports need to be changed to import from `react-navigation-drawer`:

- `createDrawerNavigator`
- `DrawerGestureContext`
- `DrawerRouter`
- `DrawerActions`
- `DrawerView`
- `DrawerNavigatorItems`
- `DrawerSidebar`

## Upgrading navigators (optional)

You don't need to upgrade the navigators to their latest version when upgrading to `react-navigation@4.x`. You can upgrade them separately later as per your convenience.

> Note: We recommend to do each of these changes in a separate commit so you can revert back to a good state if something goes wrong with the upgrade.

### Installing dependencies

The latest drawer and tabs depend on [`react-native-gesture-handler`](https://github.com/software-mansion/react-native-gesture-handler) and [`react-native-reanimated`](https://github.com/software-mansion/react-native-reanimated). If you already have these libraries installed and at the latest version, you are done here! Otherwise, read on for installation instructions for these dependencies.

#### Installing dependencies into an Expo managed project

In your project directory, run the following:

```bash
npx expo install react-native-gesture-handler react-native-reanimated
```

This will install versions of these libraries that are compatible.

#### Installing dependencies into a bare React Native project

In your project directory, run `npm install react-native-reanimated react-native-gesture-handler react-native-screens`.

Next, we need to link these libraries. The steps depends on your React Native version:

- **React Native 0.60 and higher**

  On newer versions of React Native, [linking is automatic](https://github.com/react-native-community/cli/blob/master/docs/autolinking.md).

  To complete the linking on iOS, make sure you have [Cocoapods](https://cocoapods.org/) installed. Then run:

  ```bash
  cd ios
  pod install
  cd ..
  ```

- **React Native 0.59 and lower**

  If you're on an older React Native version, you need to manually link the dependencies. To do that, run:

  ```bash
  react-native link react-native-reanimated
  react-native link react-native-gesture-handler
  ```

To finalize installation of `react-native-gesture-handler` for Android, make the following modifications to `MainActivity.java`:

```diff
package com.reactnavigation.example;

import com.facebook.react.ReactActivity;
+ import com.facebook.react.ReactActivityDelegate;
+ import com.facebook.react.ReactRootView;
+ import com.swmansion.gesturehandler.react.RNGestureHandlerEnabledRootView;

public class MainActivity extends ReactActivity {

  @Override
  protected String getMainComponentName() {
    return "Example";
  }

+  @Override
+  protected ReactActivityDelegate createReactActivityDelegate() {
+    return new ReactActivityDelegate(this, getMainComponentName()) {
+      @Override
+      protected ReactRootView createRootView() {
+       return new RNGestureHandlerEnabledRootView(MainActivity.this);
+      }
+    };
+  }
}
```

### Upgrading packages

#### `react-navigation-tabs`

To upgrade `react-navigation-tabs`, run:

```bash npm2yarn
npm install react-navigation-tabs
```

This version upgrades [`react-native-tab-view`](https://github.com/react-navigation/react-navigation/tree/main/packages/react-native-tab-view) to 2.x. As a result, the animations in `createMaterialTopTabNavigator` now use the [`react-native-reanimated`](https://github.com/software-mansion/react-native-reanimated) library.

##### Breaking changes

- If you have a custom tab bar in `createMaterialTopTabNavigator` which uses the `position` prop, you'll need to update it to use `Animated` from `react-native-reanimated` instead of `react-native`.
- The `activeTintColor` and `inactiveTintColor` options for the tab bar of `createMaterialTopTabNavigator` now controls the opacity of the label and icons as well.
- The `animationsEnabled` and `optimizationsEnabled` options have been removed from `createMaterialTopTabNavigator`.
- Support for React < 16.3 has been dropped, which means the minimum supported React Native version is now 0.56.

##### New features

- A new `lazyPlaceholderComponent` option is added which lets you show a placeholder for lazy loaded tabs.

#### `react-navigation-drawer`

To upgrade `react-navigation-drawer`, run:

```bash npm2yarn
npm install react-navigation-drawer
```

This version upgrades now uses the [`react-native-reanimated`](https://github.com/software-mansion/react-native-reanimated) library for animations. This means, if you're using the `drawerProgress` value, you'll need to migrate your code to use `Animated` from `react-native-reanimated`.

#### `react-navigation-stack`

To upgrade `react-navigation-stack`, run:

```bash npm2yarn
npm install react-navigation-stack
```

In this release, we have moved several options into `navigationOptions` so that you can configure options per screen instead of per navigator. This lets you do things like customize animations for a particular screen, set options based on `screenProps` etc. Usage of built-in components such as `Header` and `HeaderBackButton` has also been simplified. Other changes are made to improve consistency within the API.

From this version, all state changes have an animation, including `replace` and `reset` which didn't do an animation previously. If you don't want animations, you can specify `animationEnabled: false` in `navigationOptions` for a specific screen, or in `defaultNavigationOptions` for the whole navigator.

> Note: The alpha versions for 2.0 used Reanimated for the animations. We've replaced Reanimated with React Native's Animated API in the stable release. If you did any custom animations with the alpha, please migrate your code to the Animated API.

##### New peer dependencies

The new version requires 2 new peer dependencies. To install them in your project, run:

```bash npm2yarn
npm install react-native-safe-area-context @react-native-community/masked-view
```

##### Stack Navigator config

The following configuration options have been removed or moved:

- `cardShadowEnabled` - moved to `navigationOptions`
- `cardOverlayEnabled` - moved to `navigationOptions`
- `cardStyle` - moved to `navigationOptions`
- `transparentCard` - removed in favor of `cardStyle: { backgroundColor: 'transparent' }` in `navigationOptions`
- `headerBackTitleVisible` - moved to `navigationOptions`
- `headerLayoutPreset` - moved to `navigationOptions` as `headerTitleAlign`
- `onTransitionStart` - moved to `navigationOptions`
- `onTransitionEnd` - moved to `navigationOptions`
- `headerTransitionPreset` - removed in favor of [new APIs for animations](stack-navigator.md#animations) in `navigationOptions`
- `transitionConfig` - removed in favor of [new APIs for animations](stack-navigator.md#animations) in `navigationOptions`

##### `navigationOptions`

The following `navigationOptions` have been removed or changed:

- `headerForceInset` - use `safeAreaInsets` instead to control the safe areas, or use `headerStatusBarHeight` to control the padding for the status bar.
- `gesturesEnabled` - renamed to `gestureEnabled` for consistency.
- `header` - now accepts a function returning react element instead, use `headerShown: false` instead of `header: null` to hide the header.
- `headerTitle` - now accepts a function returning a React element or a string.
- `headerLeft` - now accepts a function returning a React element.
- `headerRight` - now accepts a function returning a React element.
- `headerBackImage` - now accepts a function returning a React element.
- `headerBackTitle` - now specifies the back title visible in current screen instead of next, specifying `null` no longer hides back title, use `backTitleVisible` instead, for a screen to change next screen's back title, it can pass params.
- `headerBackground` - now accepts a function returning a React element.

The following `navigationOptions` have been added:

- `gestureEnabled`
- `animationEnabled`
- `headerTitleAlign`
- `cardShadowEnabled`
- `cardOverlayEnabled`
- `cardStyle`
- `headerBackgroundStyle`
- `headerBackTitleVisible`
- `swipeVelocityImpact`
- `onTransitionStart`
- `onTransitionEnd`

You can find more details about these options in the [documentation](stack-navigator.md#navigationoptions-for-screens-inside-of-the-navigator).

##### Library exports

The library now exports the following items:

- `createStackNavigator`
- `StackView`
- `Header`
- `HeaderTitle`
- `HeaderBackButton`
- `HeaderBackground`
- `CardStyleInterpolators`
- `HeaderStyleInterpolators`
- `TransitionSpecs`
- `TransitionPresets`
- `CardAnimationContext`
- `GestureHandlerRefContext`
- `HeaderHeightContext`
- `useCardAnimation`
- `useHeaderHeight`
- `useGestureHandlerRef`

The following components now receive different set of props, so if you use them, or use your own custom component, you will need to update them:

###### `Header` (`header` option)

- `mode`
- `layout`
- `scene`
- `previous`
- `navigation`
- `styleInterpolator`

###### `HeaderBackButton` (`headerLeft` option)

- `disabled`
- `onPress`
- `pressColorAndroid`
- `backImage`
- `tintColor`
- `label`
- `truncatedLabel`
- `labelVisible`
- `labelStyle`
- `allowFontScaling`
- `onLabelLayout`
- `screenLayout`
- `titleLayout`
- `canGoBack`

##### Removal of `Transitioner`

The old `Transitioner` component has been removed as a result of rewrite of the animation logic. We're not going to expose the new animation logic since it's internal implementation detail and we want to be able to change it without breaking your code. If you need `Transitioner` in your project for some reason, you can copy the old files into your project [Transitioner.tsx](https://github.com/react-navigation/stack/blob/1.0/src/views/Transitioner.tsx).

## TypeScript

If you're using TypeScript, you'll also need to upgrade the navigators to the latest version following the previous section. Since the navigators have been extracted out, navigator specific types have been removed from the main package. You'll need to update the types accordingly:

- Replace `NavigationScreenProp` with:
  - `NavigationSwitchProp` for `createSwitchNavigator` from `react-navigation`
  - `NavigationStackProp` for `createStackNavigator` from `react-navigation-stack`
  - `NavigationTabProp` for `createBottomTabNavigator` and `createMaterialTopTabNavigator` from `react-navigation-tabs`
  - `NavigationDrawerProp` for `createDrawerNavigator` from `react-navigation-drawer`
- Replace `NavigationScreenProps` with:
  - `NavigationSwitchScreenProps` for `createSwitchNavigator` from `react-navigation`
  - `NavigationStackScreenProps` for `createStackNavigator` from `react-navigation-stack`
  - `NavigationTabScreenProps` for `createBottomTabNavigator` and `createMaterialTopTabNavigator` from `react-navigation-tabs`
  - `NavigationDrawerScreenProps` for `createDrawerNavigator` from `react-navigation-drawer`
- Replace `NavigationScreenOptions` with:
  - `NavigationStackOptions` for `createStackNavigator` from `react-navigation-stack`
  - `NavigationBottomTabOptions` for `createBottomTabNavigator` from `react-navigation-tabs`
  - `NavigationMaterialTabOptions` for `createMaterialTopTabNavigator` from `react-navigation-tabs`
  - `NavigationDrawerOptions` for `createDrawerNavigator` from `react-navigation-drawer`
- Replace `NavigationScreenComponent` with:
  - `NavigationSwitchScreenComponent` for `createSwitchNavigator` from `react-navigation`
  - `NavigationStackScreenComponent` for `createStackNavigator` from `react-navigation-stack`
  - `NavigationBottomTabScreenComponent` for `createBottomTabNavigator` from `react-navigation-tabs`
  - `NavigationMaterialTabScreenComponent` for `createMaterialTopTabNavigator` from `react-navigation-tabs`
  - `NavigationDrawerScreenComponent` for `createDrawerNavigator` from `react-navigation-drawer`

See the [TypeScript guide](typescript.md) for more details.

TypeScript support is still a work in progress, so please open an issue if you're facing a problem.

---

## Navigation prop reference

Source: https://reactnavigation.org/docs/4.x/navigation-prop

Each `screen` component in your app is provided with the `navigation` prop automatically. The prop contains various convenience functions that dispatch navigation actions on the route's router. It looks like this:

- `this.props.navigation`
  - `navigate` - go to another screen, figures out the action it needs to take to do it
  - `goBack` - close active screen and move back in the stack
  - `addListener` - subscribe to updates to navigation lifecycle
  - `isFocused` - function that returns `true` if the screen is focused and `false` otherwise.
  - `state` - current state/routes
  - `setParams` - make changes to route's params
  - `getParam` - get a specific param with fallback
  - `dispatch` - send an action to router
  - `dangerouslyGetParent` - function that returns the parent navigator, if any

It's important to highlight the `navigation` prop is _not_ passed in to _all_ components; only `screen` components receive this prop automatically! React Navigation doesn't do anything magic here. For example, if you were to define a `MyBackButton` component and render it as a child of a screen component, you would not be able to access the `navigation` prop on it. If, however, you wish to access the `navigation` prop in any of your components, you may use the [`withNavigation`](with-navigation.md) HOC.

### Navigator-dependent functions

There are several additional functions present on `this.props.navigation` based on the kind of the current navigator.

If the navigator is a stack navigator, several alternatives to `navigate` and `goBack` are provided and you can use whichever you prefer. The functions are:

- `this.props.navigation`
  - `push` - push a new route onto the stack
  - `pop` - go back in the stack
  - `popToTop` - go to the top of the stack
  - `replace` - replace the current route with a new one
  - `reset` - wipe the navigator state and replace it with the result of several actions
  - `dismiss` - dismiss the current stack

If the navigator is a drawer navigator, the following are also available:

- `this.props.navigation`
  - `openDrawer` - open the drawer
  - `closeDrawer` - close the drawer
  - `toggleDrawer` - toggle the state, ie. switch from closed to open and vice versa

## Common API reference

The vast majority of your interactions with the `navigation` prop will involve `navigate`, `goBack`, `state`, and `setParams` / `getParam`.

### `navigate` - Link to other screens

Call this to link to another screen in your app. Takes the following arguments:

`navigation.navigate({ routeName, params, action, key })`

OR

`navigation.navigate(routeName, params, action)`

- `routeName` - A destination routeName that has been registered somewhere in the app's router
- `params` - Params to merge into the destination route
- `action` - (advanced) The sub-action to run in the child router, if the screen is a navigator. See [Actions Doc](navigation-actions.md) for a full list of supported actions.
- `key` - Optional identifier of what route to navigate to. Navigate **back** to this route, if it already exists

```js
class HomeScreen extends React.Component {
  render() {
    const { navigate } = this.props.navigation;

    return (
      <View>
        <Text>This is the home screen of the app</Text>
        <Button
          onPress={() => navigate('Profile', { name: 'Brent' })}
          title="Go to Brent's profile"
        />
      </View>
    );
  }
}
```

### `goBack` - Close the active screen and move back

Optionally provide a key, which specifies the route to go back from. By default, `goBack` will close the route that it is called from. If the goal is to go back _anywhere_, without specifying what is getting closed, call `.goBack(null);` Note that the `null` parameter is useful in the case of nested `StackNavigators` to go back on a parent navigator when the child navigator already has only one item in the stack. Don't be concerned if this is confusing, this API needs some work.

Note -- a key is not the name of the route but the unique identifier you provided when navigating to the route. See [navigation key](navigation-key.md).

```js
class HomeScreen extends React.Component {
  render() {
    const { goBack } = this.props.navigation;
    return (
      <View>
        <Button onPress={() => goBack()} title="Go back from this HomeScreen" />
        <Button onPress={() => goBack(null)} title="Go back anywhere" />
        <Button
          onPress={() => goBack('key-123')}
          title="Go back from key-123"
        />
      </View>
    );
  }
}
```

### Going back from a specific screen with `goBack`

Consider the following navigation stack history:

```javascript
navigation.navigate({ routeName: SCREEN, key: SCREEN_KEY_A });
navigation.navigate({ routeName: SCREEN, key: SCREEN_KEY_B });
navigation.navigate({ routeName: SCREEN, key: SCREEN_KEY_C });
navigation.navigate({ routeName: SCREEN, key: SCREEN_KEY_D });
```

Now you are on _screen D_ and want to go back to _screen A_ (popping D, C, and B).
Then you need to supply a key to goBack _FROM_:

```
navigation.goBack(SCREEN_KEY_B) // will go to screen A FROM screen B
```

Alternatively, as _screen A_ is the top of the stack, you can use `navigation.popToTop()`.

### `addListener` - Subscribe to updates to navigation lifecycle

React Navigation emits events to screen components that subscribe to them:

- `willFocus` - the screen will focus
- `didFocus` - the screen focused (if there was a transition, the transition completed)
- `willBlur` - the screen will be unfocused
- `didBlur` - the screen unfocused (if there was a transition, the transition completed)

Example:

```javascript
const didBlurSubscription = this.props.navigation.addListener(
  'didBlur',
  (payload) => {
    console.debug('didBlur', payload);
  }
);

// Remove the listener when you are done
didBlurSubscription.remove();
```

The JSON payload:

```javascript
{
  action: { type: 'Navigation/COMPLETE_TRANSITION', key: 'StackRouterRoot' },
  context: 'id-1518521010538-2:Navigation/COMPLETE_TRANSITION_Root',
  lastState: undefined,
  state: undefined,
  type: 'didBlur',
};
```

You can also subscribe to navigation events declaratively with the [`<NavigationEvents/>`](navigation-events.md) component.

### `isFocused` - Query the focused state of the screen

Returns `true` if the screen is focused and `false` otherwise.

```js
let isFocused = this.props.navigation.isFocused();
```

You probably want to use [withNavigationFocus](with-navigation-focus.md) instead of using this directly, it will pass in an `isFocused` boolean a prop to your component.

### `state` - The screen's current state/route

A screen has access to its route via `this.props.navigation.state`. Each will return an object with the following:

```js
{
  // the name of the route config in the router
  routeName: 'profile',
  //a unique identifier used to sort routes
  key: 'main0',
  //an optional object of string options for this screen
  params: { hello: 'world' }
}
```

This is most commonly used to access the `params` for the screen, passed in through `navigate` or `setParams`.

```js
class ProfileScreen extends React.Component {
  render() {
    return <Text>Name: {this.props.navigation.state.params.name}</Text>;
  }
}
```

### `setParams` - Make changes to route params

Firing the `setParams` action allows a screen to change the params in the route, which is useful for updating the header buttons and title. `setParams` works like React's `setState` - it merges the provided params object with the current params.

```js
class ProfileScreen extends React.Component {
  render() {
    return (
      <Button
        onPress={() => this.props.navigation.setParams({ name: 'Lucy' })}
        title="Set title name to 'Lucy'"
      />
    );
  }
}
```

### `getParam` - Get a specific param value with a fallback

In the past, you may have encountered the frightful scenario of accessing a `param` when `params` is undefined. Instead of accessing the param directly, you can call `getParam` instead.

Before:

```js
const { name } = this.props.navigation.state.params;
```

if `params` is `undefined`, this fails

After:

```js
const name = this.props.navigation.getParam('name', 'Peter');
```

if `name` or `params` are undefined, set the fallback to `Peter`.

## Stack Actions

The following actions will work within any stack navigator:

### Push

Similar to navigate, push will move you forward to a new route in the stack. This differs from `navigate` in that `navigate` will pop back to earlier in the stack if a route of the given name is already present there. `push` will always add on top, so a route can be present multiple times.

```js
navigation.push(routeName, params, action);
```

- `routeName` - A destination routeName that has been registered somewhere in the app's router.
- `params` - Params to merge into the destination route.
- `action` - (advanced) The sub-action to run in the child router, if the screen is a navigator. See [Actions Doc](navigation-actions.md) for a full list of supported actions.

### Pop

Take you to the previous screen in the stack. If you provide a number, `n`, it will specify how many screens to take you back within the stack.

```js
navigation.pop(n);
```

### PopToTop

Call this to jump back to the top route in the stack, dismissing all other screens.

```js
navigation.popToTop();
```

### Replace

Call this to replace the current screen with the given route, with params and sub-action.

```js
navigation.replace(routeName, params, action);
```

### Reset

Wipe the navigator state and replace it with the result of several actions.

```js
navigation.reset([NavigationActions.navigate({ routeName: 'Profile' })], 0);
```

### Dismiss

Call this if you're in a nested (child) stack and want to dismiss the entire stack, returning to the parent stack.

```js
navigation.dismiss();
```

## Advanced API Reference

The `dispatch` function is much less commonly used, but a good escape hatch if you can't do what you need with `navigate` and `goBack`.

### `dispatch` - Send an action to the router

Use dispatch to send any navigation action to the router. The other navigation functions use dispatch behind the scenes.

Note that if you want to dispatch react-navigation actions you should use the action creators provided in this library.

See [Navigation Actions Docs](navigation-actions.md) for a full list of available actions.

```js
import { NavigationActions } from 'react-navigation';

const navigateAction = NavigationActions.navigate({
  routeName: 'Profile',
  params: {},

  // navigate can have a nested navigate action that will be run inside the child router
  action: NavigationActions.navigate({ routeName: 'SubProfileRoute' }),
});
this.props.navigation.dispatch(navigateAction);
```

### `dangerouslyGetParent` - get parent navigator

If, for example, you have a screen component that can be presented within multiple navigators, you may use this to influence its behavior based on what navigator it is in.

Another good use case for this is to find the index of the active route in the parent's route list. So in the case of a stack if you are at index 0 then you may not want to render a back button, but if you're somewhere else in the list then you would render a back button.

Be sure to always check that the call returns a valid value.

```js
class UserCreateScreen extends Component {
  static navigationOptions = ({ navigation }) => {
    const parent = navigation.dangerouslyGetParent();
    const gesturesEnabled =
      parent &&
      parent.state &&
      parent.state.routeName === 'StackWithEnabledGestures';

    return {
      title: 'New User',
      gesturesEnabled,
    };
  };
}
```

---

## NavigationContext

Source: https://reactnavigation.org/docs/4.x/navigation-context

`NavigationContext` provides the `navigation` object (similar to the [navigation](navigation-prop.md) prop). In fact, [withNavigation](with-navigation.md) uses this context to inject the `navigation` prop to your wrapped component. The [hook counterpart](https://github.com/react-navigation/react-navigation-hooks#usenavigation) is essentially an `useContext` with this context as well.

Most of the time, you won't use `NavigationContext` directly, as the provided `withNavigation` and [hooks](https://github.com/react-navigation/react-navigation-hooks) already cover most use cases. But just in case you have something else in mind, `NavigationContext` is available for you to use.

## Example with hooks

```js
import { useState, useContext, useEffect } from 'react';
import { NavigationContext } from 'react-navigation';

export function useFocusState() {
  const navigation = useContext(NavigationContext);
  const isFocused = navigation.isFocused();
  const [focusState, setFocusState] = useState(getInitialFocusState(isFocused));
  function handleEvt(e) {
    const newState = focusStateOfEvent(e.type);
    newState && setFocusState(newState);
  }
  useEffect(() => {
    const subsA = navigation.addListener('action', handleEvt);
    const subsWF = navigation.addListener('willFocus', handleEvt);
    const subsDF = navigation.addListener('didFocus', handleEvt);
    const subsWB = navigation.addListener('willBlur', handleEvt);
    const subsDB = navigation.addListener('didBlur', handleEvt);
    return () => {
      subsA.remove();
      subsWF.remove();
      subsDF.remove();
      subsWB.remove();
      subsDB.remove();
    };
  });
  return focusState;
}
```

---

## NavigationEvents reference

Source: https://reactnavigation.org/docs/4.x/navigation-events

`NavigationEvents` is a React component providing a declarative API to subscribe to navigation events. It will subscribe to navigation events on mount, and unsubscribe on unmount.

### Component props

- `navigation` - navigation props (optional, defaults to reading from React context)
- `onWillFocus` - event listener
- `onDidFocus` - event listener
- `onWillBlur` - event listener
- `onDidBlur` - event listener

The event listener is the same as the imperative [`navigation.addListener(...)`](navigation-prop.md#addlistener---subscribe-to-updates-to-navigation-lifecycle) API.

### Example

```jsx harmony
import React from 'react';
import { View } from 'react-native';
import { NavigationEvents } from 'react-navigation';

const MyScreen = () => (
  <View>
    <NavigationEvents
      onWillFocus={(payload) => console.log('will focus', payload)}
      onDidFocus={(payload) => console.log('did focus', payload)}
      onWillBlur={(payload) => console.log('will blur', payload)}
      onDidBlur={(payload) => console.log('did blur', payload)}
    />
    {/*
      Your view code
    */}
  </View>
);

export default MyScreen;
```

---

## createStackNavigator

Source: https://reactnavigation.org/docs/4.x/stack-navigator

Provides a way for your app to transition between screens where each new screen is placed on top of a stack.

By default the stack navigator is configured to have the familiar iOS and Android look & feel: new screens slide in from the right on iOS, fade in from the bottom on Android. On iOS the stack navigator can also be configured to a modal style where screens slide in from the bottom.

To use this navigator, ensure that you have [react-navigation and its dependencies installed](getting-started.md), then install [`react-navigation-stack`](https://github.com/react-navigation/react-navigation/tree/4.x/packages/stack).

```bash npm2yarn
npm install react-navigation-stack @react-native-community/masked-view
```

## API Definition

```js
import { createStackNavigator } from 'react-navigation-stack';

createStackNavigator(RouteConfigs, StackNavigatorConfig);
```

### RouteConfigs

The route configs object is a mapping from route name to a route config, which tells the navigator what to present for that route.

```js
createStackNavigator({
  // For each screen that you can navigate to, create a new entry like this:
  Profile: {
    // `ProfileScreen` is a React component that will be the main content of the screen.
    screen: ProfileScreen,
    // When `ProfileScreen` is loaded by the StackNavigator, it will be given a `navigation` prop.

    // Optional: When deep linking or using react-navigation in a web app, this path is used:
    path: 'people/:name',
    // The action and route params are extracted from the path.

    // Optional: Override the `navigationOptions` for the screen
    navigationOptions: ({ navigation }) => ({
      title: `${navigation.state.params.name}'s Profile'`,
    }),
  },

  ...MyOtherRoutes,
});
```

### StackNavigatorConfig

Options for the router:

- `initialRouteName` - Sets the default screen of the stack. Must match one of the keys in route configs.
- `initialRouteParams` - The params for the initial route
- `initialRouteKey` - Optional identifier of the initial route
- `navigationOptions` - Navigation options for the navigator itself, to configure a parent navigator
- `defaultNavigationOptions` - Default navigation options to use for screens
- `paths` - A mapping of overrides for the paths set in the route configs
- `detachInactiveScreens` - Boolean used to indicate whether inactive screens should be detached from the view hierarchy to save memory. Make sure to call `enableScreens` from [react-native-screens](https://github.com/software-mansion/react-native-screens) to make it work. Defaults to `true` on Android and `false` on iOS.

Visual options:

- `mode` - Defines the style for rendering and transitions:
  - `card` - Use the standard iOS and Android screen transitions. This is the default.
  - `modal` - This does few things:
    - Sets `headerMode` to `screen` for the stack unless specified
    - Prevents last inactive screen from being detached so that it stays visible underneath the active screen
    - Make the screens slide in from the bottom on iOS which is a common iOS pattern.
- `headerMode` - Specifies how the header should be rendered:
  - `float` - The header is rendered above the screen and animates independently of the screen. This is default on iOS for non-modals.
  - `screen` - The header is rendered as part of the screen and animates together with the screen. This is default on other platforms.
  - `none` - No header will be rendered.
- `keyboardHandlingEnabled` - If `false`, the on screen keyboard will NOT automatically dismiss when navigating to a new screen. Defaults to `true`.

### `navigationOptions` for screens inside of the navigator

#### `title`

String that can be used as a fallback for `headerTitle`. Additionally, will be used as a fallback for `tabBarLabel` (if nested in a TabNavigator) or `drawerLabel` (if nested in a DrawerNavigator).

#### `detachPreviousScreen`

Boolean used to indicate whether to detach the previous screen from the view hierarchy to save memory. Set it to `false` if you need the previous screen to be seen through the active screen. Only applicable if `detachInactiveScreens` isn't set to `false`. Defaults to `false` for the last screen when `mode='modal'`, otherwise `true`.

#### `header`

Function that given `HeaderProps` returns a React Element, to display as a header.

Example:

```js
header: ({ scene, previous, navigation }) => {
  const { options } = scene.descriptor;
  const title =
    options.headerTitle !== undefined
      ? options.headerTitle
      : options.title !== undefined
        ? options.title
        : scene.route.routeName;

  return (
    <MyHeader
      title={title}
      leftButton={
        previous ? <MyBackButton onPress={navigation.goBack} /> : undefined
      }
      style={options.headerStyle}
    />
  );
};
```

To set a custom header for all the screens in the navigator, you can specify this option in the `defaultNavigationOptions` option of the navigator.

When using a custom header, there are 2 important things to keep in mind:

##### Specify a `height` in `headerStyle`

If your header's height differs from the default header height, then you might notice glitches due to measurement being async. Explicitly specifying the height will avoid such glitches.

Example:

```js
headerStyle: {
  height: 80, // Specify the height of your custom header
};
```

Note that this style is not applied to the header by default since you control the styling of your custom header. If you also want to apply this style to your header, use `scene.descriptor.options.headerStyle` from the props.

##### Set `headerMode` to `screen`

By default, there is one floating header which renders headers for multiple screens on iOS. These headers include animations to smoothly switch to one another.

Setting the `headerMode` prop to `screen` makes the header part of the screen, so you don't have to implement animations to animate it separately.

If you want to customize how the header animates and want to keep `headerMode` as `float`, you can interpolate on the `scene.progress.current` and `scene.progress.next` props. For example, following will cross-fade the header:

```js
const progress = Animated.add(scene.progress.current, scene.progress.next || 0);

const opacity = progress.interpolate({
  inputRange: [0, 1, 2],
  outputRange: [0, 1, 0],
});

return (
  <Animated.View style={{ opacity }}>{/* Header content */}</Animated.View>
);
```

#### `headerShown`

Whether to show or hide the header for the screen. The header is shown by default unless `headerMode` was set to `none`. Setting this to `false` hides the header.

When hiding the header on specific screens, you might also want to set `headerMode` option to `screen`.

#### `headerTitle`

String or a function that returns a React Element to be used by the header. Defaults to scene `title`. When a function is specified, it receives an object containing `allowFontScaling`, `style` and `children` properties. The `children` property contains the title string.

#### `headerTitleAlign`

How to align the header title. Possible values:

- `left`
- `center`

Defaults to `center` on iOS and `left` on Android.

#### `headerTitleAllowFontScaling`

Whether header title font should scale to respect Text Size accessibility settings. Defaults to false.

#### `headerBackAllowFontScaling`

Whether back button title font should scale to respect Text Size accessibility settings. Defaults to false.

#### `headerBackAccessibilityLabel`

Accessibility label for the header back button.

#### `headerBackImage`

Function which returns a React Element to display custom image in header's back button. When a function is used, it receives the `tintColor` in it's argument object. Defaults to Image component with `react-navigation/views/assets/back-icon.png` back image source, which is the default back icon image for the platform (a chevron on iOS and an arrow on Android).

#### `headerBackTitle`

Title string used by the back button on iOS. Defaults to the previous scene's `headerTitle`.

#### `headerBackTitleVisible`

A reasonable default is supplied for whether the back button title should be visible or not, but if you want to override that you can use `true` or `false` in this option.

#### `headerTruncatedBackTitle`

Title string used by the back button when `headerBackTitle` doesn't fit on the screen. `"Back"` by default.

#### `headerRight`

Function which returns a React Element to display on the right side of the header.

#### `headerLeft`

Function which returns a React Element to display on the left side of the header. When a function is used, it receives a number of arguments when rendered (`onPress`, `label`, `labelStyle` and more - check [types.tsx](https://github.com/react-navigation/react-navigation/blob/4.x/packages/stack/src/types.tsx) for the complete list).

#### `headerStyle`

Style object for the header. You can specify a custom background color here, for example.

#### `headerTitleStyle`

Style object for the title component

#### `headerBackTitleStyle`

Style object for the back title

#### `headerLeftContainerStyle`

Customize the style for the container of the `headerLeft` component, for example to add padding.

#### `headerRightContainerStyle`

Customize the style for the container of the `headerRight` component, for example to add padding.

#### `headerTitleContainerStyle`

Customize the style for the container of the `headerTitle` component, for example to add padding.

By default, `headerTitleContainerStyle` is with an absolute position style and offsets both `left` and `right`. This may lead to white space or overlap between `headerLeft` and `headerTitle` if a customized `headerLeft` is used. It can be solved by adjusting `left` and `right` style in `headerTitleContainerStyle` and `marginHorizontal` in `headerTitleStyle`.

#### `headerTintColor`

Tint color for the header

#### `headerPressColorAndroid`

Color for material ripple (Android >= 5.0 only)

#### `headerTransparent`

Defaults to `false`. If `true`, the header will not have a background unless you explicitly provide it with `headerBackground`. The header will also float over the screen so that it overlaps the content underneath.

This is useful if you want to render a semi-transparent header or a blurred background.

Note that if you don't want your content to appear under the header, you need to manually add a top margin to your content. React Navigation won't do it automatically.

To get the height of the header, you can use `HeaderHeightContext` with [React's Context API](https://reactjs.org/docs/context.html#contextconsumer) or `useHeaderHeight`:

```js
import { HeaderHeightContext } from 'react-navigation-stack';

// ...

<HeaderHeightContext.Consumer>
  {headerHeight => (
    /* render something */
  )}
</HeaderHeightContext.Consumer>
```

or

```js
import { useHeaderHeight } from 'react-navigation-stack';

// ...

const headerHeight = useHeaderHeight();
```

#### `headerBackground`

Function which returns a React Element to render as the background of the header. This is useful for using backgrounds such as an image or a gradient.

For example, you can use this with `headerTransparent` to render a blur view to create a translucent header.

```js
import { BlurView } from 'expo-blur';

// ...

MyScreen.navigationOptions = {
  headerTransparent: true,
  headerBackground: () => (
    <BlurView tint="light" intensity={100} style={StyleSheet.absoluteFill} />
  ),
};
```

#### `headerStatusBarHeight`

Extra padding to add at the top of header to account for translucent status bar. By default, it uses the top value from the safe area insets of the device. Pass 0 or a custom value to disable the default behavior, and customize the height.

#### `cardShadowEnabled`

Use this prop to have visible shadows during transitions. Defaults to `true`.

#### `cardOverlayEnabled`

Use this prop to have a semi-transparent dark overlay visible under the card during transitions. Defaults to `true` on Android and `false` on iOS.

#### `cardStyle`

Style object for the card in stack. You can provide a custom background color to use instead of the default background here.

You can also specify `{ backgroundColor: 'transparent' }` to make the previous screen visible underneath. This is useful to implement things like modal dialogs. You should also specify `mode: 'modal'` in the stack view config when using a transparent background so previous screens aren't detached and stay visible underneath.

#### `animationEnabled`

Whether transition animation should be enabled the screen. If you set it to `false`, the screen won't animate when pushing or popping. Defaults to `true`.

#### `animationTypeForReplace`

The type of animation to use when this screen replaces another screen. It takes the following values:

- `push` - The animation of a new screen being pushed will be used
- `pop` - The animation of a screen being popped will be used

Defaults to `push`.

When `pop` is used, the `pop` animation is applied to the screen being replaced.

#### `gestureEnabled`

Whether you can use gestures to dismiss this screen. Defaults to `true` on iOS, `false` on Android.

#### `gestureResponseDistance`

Object to override the distance of touch start from the edge of the screen to recognize gestures. It takes the following properties:

- `horizontal` - _number_ - Distance for horizontal direction. Defaults to 25.
- `vertical` - _number_ - Distance for vertical direction. Defaults to 135.

#### `gestureVelocityImpact`

Number which determines the relevance of velocity for the gesture. Defaults to 0.3.

#### `gestureDirection`

Direction of the gestures. Refer the [Animations section](#animations) for details.

#### `transitionSpec`

Configuration object for the screen transition. Refer the [Animations section](#animations) for details.

#### `cardStyleInterpolator`

Interpolated styles for various parts of the card. Refer the [Animations section](#animations) for details.

#### `headerStyleInterpolator`

Interpolated styles for various parts of the header. Refer the [Animations section](#animations) for details.

#### `safeAreaInsets`

Safe area insets for the screen. This is used to avoid elements like notch and status bar. By default, the device's safe area insets are automatically detected. You can override the behavior with this option.

Takes an object containing following optional properties: `top`, `right`, `bottom` and `left`.

#### `onTransitionStart`

Callback which is called when a transition animation starts (both when screen appears and hides).

#### `onTransitionEnd`

Callback which is called when a transition animation ends.

### `params`

You can provide default params inside route definitions:

```js
const Store = createStackNavigator({
  Playstation: { screen: ProductScreen, params: { product: 'Playstation' } },
  Xbox: { screen: ProductScreen, params: { product: 'Xbox' } },
});
```

### Examples

See the examples in the [example app](https://github.com/react-navigation/stack/tree/master/example) in the repo.

### Animations

### Animation related options

Stack Navigator exposes various options to configure the transition animation when a screen is added or removed. These transition animations can be customized on a per-screen basis by specifying the options in the `options` prop for each screen.

- `gestureDirection` - The direction of swipe gestures:
  - `horizontal` - The gesture to close the screen will start from the left, and from the right in RTL. For animations, screen will slide from the right with `SlideFromRightIOS`, and from the left in RTL.
  - `horizontal-inverted` - The gesture to close the screen will start from the right, and from the left in RTL. For animations, screen will slide from the left with `SlideFromRightIOS`, and from the right in RTL as the direction is inverted.
  - `vertical` - The gesture to close the screen will start from the top. For animations, screen will slide from the bottom.
  - `vertical-inverted` - The gesture to close the screen will start from the bottom. For animations, screen will slide from the top.

  You may want to specify a matching horizontal/vertical animation along with `gestureDirection` as well. For the animations included in the library, if you set `gestureDirection` to one of the inverted ones, it'll also flip the animation direction.

- `transitionSpec` - An object which specifies the animation type (`timing` or `spring`) and their options (such as `duration` for `timing`). It takes 2 properties:
  - `open` - Configuration for the transition when adding a screen
  - `close` - Configuration for the transition when removing a screen.

  Each of the object should specify 2 properties:
  - `animation` - The animation function to use for the animation. Supported values are `timing` and `spring`.
  - `config` - The configuration object for the timing function. For `timing`, it can be `duration` and `easing`. For `spring`, it can be `stiffness`, `damping`, `mass`, `overshootClamping`, `restDisplacementThreshold` and `restSpeedThreshold`.

  A config which uses spring animation looks like this:

  ```js
  const config = {
    animation: 'spring',
    config: {
      stiffness: 1000,
      damping: 500,
      mass: 3,
      overshootClamping: true,
      restDisplacementThreshold: 0.01,
      restSpeedThreshold: 0.01,
    },
  };
  ```

  We can pass this function in `transitionSpec` option:

  ```js
  Profile.navigationOptions = {
    transitionSpec: {
      open: config,
      close: config,
    },
  };
  ```

- `cardStyleInterpolator` - This is a function which specifies interpolated styles for various parts of the card. Is expected to return at least empty object, possibly containing interpolated styles for container, the card itself, overlay and shadow. Supported properties are:
  - `containerStyle` - Style for the container view wrapping the card.
  - `cardStyle` - Style for the view representing the card.
  - `overlayStyle` - Style for the view representing the semi-transparent overlay below
  - `shadowStyle` - Style for the view representing the card shadow.

  The function receives the following properties in it's argument:
  - `current` - Values for the current screen:
    - `progress` - Animated node representing the progress value of the current screen. `0` when screen should start coming into view, `0.5` when it's mid-way, `1` when it should be fully in view.
  - `next` - Values for the current screen the screen after this one in the stack. This can be `undefined` in case the screen animating is the last one.
    - `progress` - Animated node representing the progress value of the next screen.
  - `index` - The index of the card in the stack.
  - `closing` - Animated node representing whether the card is closing. `1` when closing, `0` if not.
  - `layouts` - Layout measurements for various items we use for animation.
    - `screen` - Layout of the whole screen. Contains `height` and `width` properties.

  A config which just fades the card looks like this:

  ```js
  const forFade = ({ current, closing }) => ({
    cardStyle: {
      opacity: current.progress,
    },
  });
  ```

  We can pass this function in `cardStyleInterpolator` option:

  ```js
  Profile.navigationOptions = {
    cardStyleInterpolator: forFade,
  };
  ```

- `headerStyleInterpolator` - This is a function which specifies interpolated styles for various parts of the header. Is expected to return at least empty object, possibly containing interpolated styles for left label and button, right button, title and background. Supported properties are:
  - `leftLabelStyle` - Style for the label of the left button (back button label).
  - `leftButtonStyle` - Style for the left button (usually the back button).
  - `rightButtonStyle` - Style for the right button.
  - `titleStyle` - Style for the header title text.
  - `backgroundStyle` - Style for the header background.

  The function receives the following properties in it's argument:
  - `current` - Values for the current screen (the screen which owns this header).
    - `progress` - Animated node representing the progress value of the current screen.
  - `next` - Values for the current screen the screen after this one in the stack. This can be `undefined` in case the screen animating is the last one.
    - `progress` - Animated node representing the progress value of the next screen.
  - `layouts` - Layout measurements for various items we use for animation. Each layout object contain `height` and `width` properties.
    - `screen` - Layout of the whole screen.
    - `title` - Layout of the title element. Might be `undefined` when not rendering a title.
    - `leftLabel` - Layout of the back button label. Might be `undefined` when not rendering a back button label.

  A config which just fades the elements looks like this:

  ```js
  const forFade = ({ current, next }) => {
    const opacity = Animated.add(
      current.progress,
      next ? next.progress : 0
    ).interpolate({
      inputRange: [0, 1, 2],
      outputRange: [0, 1, 0],
    });

    return {
      leftButtonStyle: { opacity },
      rightButtonStyle: { opacity },
      titleStyle: { opacity },
      backgroundStyle: { opacity },
    };
  };
  ```

  We can pass this function in `headerStyleInterpolator` option:

  ```js
  Profile.navigationOptions = {
    headerStyleInterpolator: forFade,
  };
  ```

### Pre-made configs

With these options, it's possible to build custom transition animations for screens. We also export various configs from the library with ready-made animations which you can use:

#### `TransitionSpecs`

- `TransitionIOSSpec` - Exact values from UINavigationController's animation configuration.
- `FadeInFromBottomAndroidSpec` - Configuration for activity open animation from Android Nougat.
- `FadeOutToBottomAndroidSpec` - Configuration for activity close animation from Android Nougat.
- `RevealFromBottomAndroidSpec` - Approximate configuration for activity open animation from Android Pie.

```js
import { TransitionSpecs } from 'react-navigation-stack';

// ...

static navigationOptions = {
  title: 'Profile',
  transitionSpec: {
    open: TransitionSpecs.TransitionIOSSpec,
    close: TransitionSpecs.TransitionIOSSpec,
  },
}
```

#### `CardStyleInterpolators`

- `forHorizontalIOS` - Standard iOS-style slide in from the right.
- `forVerticalIOS` - Standard iOS-style slide in from the bottom (used for modals).
- `forModalPresentationIOS` - Standard iOS-style modal animation in iOS 13.
- `forFadeFromBottomAndroid` - Standard Android-style fade in from the bottom for Android Oreo.
- `forRevealFromBottomAndroid` - Standard Android-style reveal from the bottom for Android Pie.

Example configuration for Android Oreo style vertical screen fade animation:

```js
import { CardStyleInterpolators } from 'react-navigation-stack';

// ...

static navigationOptions = {
  title: 'Profile',
  cardStyleInterpolator: CardStyleInterpolators.forFadeFromBottomAndroid,
}
```

#### `HeaderStyleInterpolators`

- `forUIKit` - Standard UIKit style animation for the header where the title fades into the back button label.
- `forFade` - Simple fade animation for the header elements.
- `forStatic` - Simple translate animation to translate the header along with the sliding screen.

Example configuration for default iOS animation for header elements where the title fades into the back button:

```js
import { HeaderStyleInterpolators } from 'react-navigation-stack';

// ...

static navigationOptions = {
  title: 'Profile',
  headerStyleInterpolator: HeaderStyleInterpolators.forUIKit,
}
```

> Note: Always define your animation configuration at the top-level of the file to ensure that the references don't change across re-renders. This is important for smooth and reliable transition animations.

#### `TransitionPresets`

We export various transition presets which bundle various set of these options together to match certain native animations. A transition preset is an object containing few animation related screen options exported under `TransitionPresets`. Currently the following presets are available:

- `SlideFromRightIOS` - Standard iOS navigation transition.
- `ModalSlideFromBottomIOS` - Standard iOS navigation transition for modals.
- `ModalPresentationIOS` - Standard iOS modal presentation style (introduced in iOS 13).
- `FadeFromBottomAndroid` - Standard Android navigation transition when opening or closing an Activity on Android < 9 (Oreo).
- `RevealFromBottomAndroid` - Standard Android navigation transition when opening or closing an Activity on Android >= 9 (Pie).
- `DefaultTransition` - Default navigation transition for the current platform.
- `ModalTransition` - Default modal transition for the current platform.

You can spread these presets in `navigationOptions` to customize the animation for a screen:

```js
import { TransitionPresets } from 'react-navigation-stack';

// ...

static navigationOptions = {
  title: 'Profile',
  ...TransitionPresets.ModalSlideFromBottomIOS
}
```

If you want to customize the transition animations for all of the screens in the navigator, you can specify it in `defaultNavigationOptions` when defining a navigator.

Example configuration for iOS modal presentation style:

```js
import { TransitionPresets } from 'react-navigation-stack';

// ...

const Stack = createStackNavigator(
  {
    Home,
    Profile,
    Settings,
  },
  {
    mode: 'modal',
    headerMode: 'none',
    defaultNavigationOptions: {
      gestureEnabled: true,
      cardOverlayEnabled: true,
      ...TransitionPresets.ModalPresentationIOS,
    },
  }
);
```

---

## createStackNavigator (1.x)

Source: https://reactnavigation.org/docs/4.x/stack-navigator-1.0

Provides a way for your app to transition between screens where each new screen is placed on top of a stack.

By default the stack navigator is configured to have the familiar iOS and Android look & feel: new screens slide in from the right on iOS, fade in from the bottom on Android. On iOS the stack navigator can also be configured to a modal style where screens slide in from the bottom.

To use this navigator, ensure that you have [react-navigation and its dependencies installed](getting-started.md), then install [`react-navigation-stack`](https://github.com/react-navigation/stack/tree/1.0).

```bash npm2yarn
npm install react-navigation-stack@^1.10.3
```

## API

```js
import { createStackNavigator } from 'react-navigation-stack';

createStackNavigator(RouteConfigs, StackNavigatorConfig);
```

### RouteConfigs

The route configs object is a mapping from route name to a route config, which tells the navigator what to present for that route.

```js
createStackNavigator({
  // For each screen that you can navigate to, create a new entry like this:
  Profile: {
    // `ProfileScreen` is a React component that will be the main content of the screen.
    screen: ProfileScreen,
    // When `ProfileScreen` is loaded by the StackNavigator, it will be given a `navigation` prop.

    // Optional: When deep linking or using react-navigation in a web app, this path is used:
    path: 'people/:name',
    // The action and route params are extracted from the path.

    // Optional: Override the `navigationOptions` for the screen
    navigationOptions: ({ navigation }) => ({
      title: `${navigation.state.params.name}'s Profile'`,
    }),
  },

  ...MyOtherRoutes,
});
```

### StackNavigatorConfig

Options for the router:

- `initialRouteName` - Sets the default screen of the stack. Must match one of the keys in route configs.
- `initialRouteParams` - The params for the initial route
- `initialRouteKey` - Optional identifier of the initial route

- `navigationOptions` - Navigation options for the navigator itself, to configure a parent navigator
- `defaultNavigationOptions` - Default navigation options to use for screens

- `paths` - A mapping of overrides for the paths set in the route configs
- `disableKeyboardHandling` - If true, the keyboard will NOT automatically dismiss when navigating to a new screen. Defaults to false. This is ignored in the web platform.

Visual options:

- `mode` - Defines the style for rendering and transitions:
  - `card` - Use the standard iOS and Android screen transitions. This is the default.
  - `modal` - Make the screens slide in from the bottom which is a common iOS pattern. Only works on iOS, has no effect on Android.
- `headerMode` - Specifies how the header should be rendered:
  - `float` - Render a single header that stays at the top and animates as screens are changed. This is a common pattern on iOS.
  - `screen` - Each screen has a header attached to it and the header fades in and out together with the screen. This is a common pattern on Android.
  - `none` - No header will be rendered.
- `headerBackTitleVisible` - A reasonable default is supplied for whether the back button title should be visible or not, but if you want to override that you can use `true` or `false` in this option.
- `headerTransitionPreset` - Specifies how the header should transition from one screen to another when `headerMode: float` is enabled.
  - `fade-in-place` - Header components cross-fade without moving, similar to the Twitter, Instagram, and Facebook app for iOS. This is the default value.
  - `uikit` - An approximation of the default behavior for iOS.
- `headerLayoutPreset` - Specifies how to lay out the header components.
  - `left` - Anchor the title to the left, near the back button or other left component. This is the default on Android. When used on iOS, the header back title is hidden. Content from the left component will overflow underneath the title, if you need to adjust this you can use `headerLeftContainerStyle` and `headerTitleContainerStyle`. Additionally, this alignment is incompatible with `headerTransitionPreset: 'uikit'`.
  - `center` - Center the title, this is the default on iOS.
- `cardStyle` - Use this prop to override or extend the default style for an individual card in stack.
- `cardShadowEnabled` - Use this prop to have visible shadows during transitions. Defaults to `true`
- `cardOverlayEnabled` - Use this prop to have visible stack card overlays during transitions. Defaults to `false`.
- `transitionConfig` - Function to return an object that is merged with the default screen transitions (take a look at TransitionConfig in [type definitions](https://github.com/react-navigation/stack/blob/1.0/src/types.tsx#L232)). Provided function will be passed the following arguments:
  - `transitionProps` - Transition props for the new screen.
  - `prevTransitionProps` - Transitions props for the old screen.
  - `isModal` - Boolean specifying if screen is modal.
- `onTransitionStart` - Function to be invoked when the card transition animation is about to start.
- `onTransitionEnd` - Function to be invoked once the card transition animation completes.
- `transparentCard` - _Experimental_ - Prop to keep all cards in the stack visible and add a transparent background instead of a white one. This is useful to implement things like modal dialogs where the previous scene should still be visible underneath the current one.

### `navigationOptions` for screens inside of the navigator

#### `title`

String that can be used as a fallback for `headerTitle`. Additionally, will be used as a fallback for `tabBarLabel` (if nested in a TabNavigator) or `drawerLabel` (if nested in a DrawerNavigator).

#### `header`

React Element or a function that given `HeaderProps` returns a React Element, to display as a header.

#### `headerShown`

Whether to show or hide the header for the screen. The header is shown by default unless `headerMode` was set to `none`. Setting this to `false` hides the header.

#### `headerTitle`

String, React Element or a function that returns a React Element to be used by the header. Defaults to scene `title`. When a function is used, it receives an object containing `allowFontScaling`, `style` and `children` properties. The `children` property contains the title string.

#### `headerTitleAllowFontScaling`

Whether header title font should scale to respect Text Size accessibility settings. Defaults to true.

#### `headerBackAllowFontScaling`

Whether back button title font should scale to respect Text Size accessibility settings. Defaults to false.

#### `headerBackImage`

Function which returns a React Element to display custom image in header's back button. When a function is used, it receives the `tintColor` in it's argument object. Defaults to Image component with back image source, which is the default back icon image for the platform (a chevron on iOS and an arrow on Android).

#### `headerBackTitle`

Title string used by the back button on iOS, or `null` to disable label. Defaults to the previous scene's `headerTitle`. `headerBackTitle` has to be defined in the origin screen, not in the destination screen. For instance, when you have a transition A to B and you want to disable the `headerBackTitle` on `B`:

```js
StackNavigator({
  A: {
    screen: AScreen,
    navigationOptions: () => ({
      title: `A`,
      headerBackTitle: null,
    }),
  },
  B: {
    screen: BScreen,
    navigationOptions: () => ({
      title: `B`,
    }),
  },
});
```

#### `headerTruncatedBackTitle`

Title string used by the back button when `headerBackTitle` doesn't fit on the screen. `"Back"` by default. `headerTruncatedBackTitle` has to be defined in the origin screen, not in the destination screen. For instance, when you have a transition A to B and you want to truncate the label on `B`:

```js
StackNavigator({
  A: {
    screen: AScreen,
    navigationOptions: () => ({
      title: `A`,
      headerBackTitle: 'A much too long text for back button from B to A',
      headerTruncatedBackTitle: `to A`,
    }),
  },
  B: {
    screen: BScreen,
    navigationOptions: () => ({
      title: `B`,
    }),
  },
});
```

#### `headerRight`

React Element to display on the right side of the header.

#### `headerLeft`

Function which returns a React Element to display on the left side of the header. When a function is used, it receives a number of arguments when rendered (`onPress`, `title`, `titleStyle` and more).

#### `headerStyle`

Style object for the header

#### `headerForceInset`

Allows to pass `forceInset` object to internal SafeAreaView used in the header.

#### `headerTitleStyle`

Style object for the title component

#### `headerBackTitleStyle`

Style object for the back title

#### `headerLeftContainerStyle`

Customize the style for the container of the `headerLeft` component, for example to add padding.

#### `headerRightContainerStyle`

Customize the style for the container of the `headerRight` component, for example to add padding.

#### `headerTitleContainerStyle`

Customize the style for the container of the `headerTitle` component, for example to add padding.

By default, `headerTitleContainerStyle` is with an absolute position style and offsets both `left` and `right`. This may lead to white space or overlap between `headerLeft` and `headerTitle` if a customized `headerLeft` is used. It can be solved by adjusting `left` and `right` style in `headerTitleContainerStyle` and `marginHorizontal` in `headerTitleStyle`.

#### `headerTintColor`

Tint color for the header

#### `headerPressColorAndroid`

Color for material ripple (Android >= 5.0 only)

#### `headerTransparent`

Defaults to `false`. If `true`, the header will not have a background unless you explicitly provide it with `headerStyle` or `headerBackground`.

#### `headerBackground`

Use this with `headerTransparent` to provide a Function which returns a React Element to render in the background of the header. You can use this with a blur view, for example, to create a translucent header.

#### `headerBackgroundTransitionPreset`

One of `toggle` | `fade` | `translate`; lets you choose how to transition your custom `headerBackground` components between screens.

#### `gesturesEnabled`

Whether you can use gestures to dismiss this screen. Defaults to true on iOS, false on Android.

#### `gestureResponseDistance`

Object to override the distance of touch start from the edge of the screen to recognize gestures. It takes the following properties:

- `horizontal` - _number_ - Distance for horizontal direction. Defaults to 25.
- `vertical` - _number_ - Distance for vertical direction. Defaults to 135.

#### `gestureDirection`

String to override the direction for dismiss gesture. `default` for normal behaviour or `inverted` for right-to-left swipes.

#### `params`

You can provide default params inside route definitions:

```js
const Store = createStackNavigator({
  Playstation: { screen: ProductScreen, params: { product: 'Playstation' } },
  Xbox: { screen: ProductScreen, params: { product: 'Xbox' } },
});
```

### Examples

See the examples [SimpleStack.tsx](https://github.com/react-navigation/react-navigation/blob/4.x/example/src/SimpleStack.tsx) and [ModalStack.tsx](https://github.com/react-navigation/react-navigation/blob/4.x/example/src/ModalStack.tsx) which you can run locally as part of the [NavigationPlayground](https://github.com/react-navigation/react-navigation/tree/4.x/example) app.

You can view these examples directly on your phone by visiting [our expo demo](https://exp.host/@react-navigation/NavigationPlayground).

#### Modal StackNavigator with Custom Screen Transitions

```js
const ModalNavigator = createStackNavigator(
  {
    Main: { screen: Main },
    Login: { screen: Login },
  },
  {
    headerMode: 'none',
    mode: 'modal',
    defaultNavigationOptions: {
      gesturesEnabled: false,
    },
    transitionConfig: () => ({
      transitionSpec: {
        duration: 300,
        easing: Easing.out(Easing.poly(4)),
        timing: Animated.timing,
      },
      screenInterpolator: (sceneProps) => {
        const { layout, position, scene } = sceneProps;
        const { index } = scene;

        const height = layout.initHeight;
        const translateY = position.interpolate({
          inputRange: [index - 1, index, index + 1],
          outputRange: [height, 0, 0],
        });

        const opacity = position.interpolate({
          inputRange: [index - 1, index - 0.99, index],
          outputRange: [0, 1, 1],
        });

        return { opacity, transform: [{ translateY }] };
      },
    }),
  }
);
```

Header transitions can also be configured using `headerLeftInterpolator`, `headerTitleInterpolator` and `headerRightInterpolator` fields under `transitionConfig`.

#### Specifying the transition mode for a stack's screens explicitly

We can't set the `StackNavigatorConfig`'s `mode` dynamically. Instead we are going to use a custom `transitionConfig` to render the specific transition we want - modal or card - on a screen by screen basis.

```js
import {
  createStackNavigator,
  StackViewTransitionConfigs,
} from 'react-navigation';

/* The screens you add to IOS_MODAL_ROUTES will have the modal transition.  */
const IOS_MODAL_ROUTES = ['OptionsScreen'];

let dynamicModalTransition = (transitionProps, prevTransitionProps) => {
  const isModal = IOS_MODAL_ROUTES.some(
    (screenName) =>
      screenName === transitionProps.scene.route.routeName ||
      (prevTransitionProps &&
        screenName === prevTransitionProps.scene.route.routeName)
  );
  return StackViewTransitionConfigs.defaultTransitionConfig(
    transitionProps,
    prevTransitionProps,
    isModal
  );
};

const HomeStack = createStackNavigator(
  { DetailScreen, HomeScreen, OptionsScreen },
  { initialRouteName: 'HomeScreen', transitionConfig: dynamicModalTransition }
);
```

## Peer dependencies

react-navigation-stack depends on the following libraries in addition to react-navigation itself:

- react-native-gesture-handler
- react-native-screens

---

## createSwitchNavigator

Source: https://reactnavigation.org/docs/4.x/switch-navigator

The purpose of SwitchNavigator is to only ever show one screen at a time. By default, it does not handle back actions and it resets routes to their default state when you switch away.
This is the exact behavior that we want from the [authentication flow](auth-flow.md).

## API Definition

```js
createSwitchNavigator(RouteConfigs, SwitchNavigatorConfig);
```

## RouteConfigs

The route configs object is a mapping from route name to a route config, which tells the navigator what to present for that route, see [example](stack-navigator.md#routeconfigs) from `createStackNavigator`.

## SwitchNavigatorConfig

Several options get passed to the underlying router to modify navigation logic:

- `initialRouteName` - The routeName for the initial tab route when first loading.
- `navigationOptions` - Navigation options for the navigator itself, to configure a parent navigator
- `defaultNavigationOptions` - Default navigation options to use for screens
- `resetOnBlur` - Reset the state of any nested navigators when switching away from a screen. Defaults to `true`.
- `paths` - Provide a mapping of routeName to path config, which overrides the paths set in the routeConfigs.
- `backBehavior` - `initialRoute` to return to initial route, `order` to return to previous route, `history` to return to last visited route, or `none`.

## Example

See an example of this [on Snack](https://snack.expo.io/@react-navigation/auth-flow-v3).

---

## createAnimatedSwitchNavigator

Source: https://reactnavigation.org/docs/4.x/animated-switch-navigator

A `SwitchNavigator` with animation support.

To use this navigator, you need to install `react-native-reanimated >= 1.0.0`. If you have a managed Expo project, you need to use >= SDK 33 to have the correct version of Reanimated.

## API Definition

```js
import createAnimatedSwitchNavigator from 'react-navigation-animated-switch';

createAnimatedSwitchNavigator(RouteConfigs, SwitchNavigatorConfig);
```

## RouteConfigs

The route configs are identical to [createSwitchNavigator](switch-navigator.md)

## SwitchNavigatorConfig

The switch navigator configs are identical to [createSwitchNavigator](switch-navigator.md).

By default, the transition between screens is a cross-fade. You can customize the transition with an additional option `transition`:

```jsx
import createAnimatedSwitchNavigator from 'react-navigation-animated-switch';
import { Transition } from 'react-native-reanimated';

const MySwitch = createAnimatedSwitchNavigator(
  {
    Home: HomeScreen,
    Other: OtherScreen,
  },
  {
    // The previous screen will slide to the bottom while the next screen will fade in
    transition: (
      <Transition.Together>
        <Transition.Out
          type="slide-bottom"
          durationMs={400}
          interpolation="easeIn"
        />
        <Transition.In type="fade" durationMs={500} />
      </Transition.Together>
    ),
  }
);
```

Since the transition are possible thanks to the `Transition` API from `react-native-reanimated`, you can learn more about it [here](https://github.com/software-mansion/react-native-reanimated).

---

## createDrawerNavigator

Source: https://reactnavigation.org/docs/4.x/drawer-navigator

To use this navigator, ensure that you have [react-navigation and its dependencies installed](getting-started.md), then install [`react-navigation-drawer`](https://github.com/react-navigation/react-navigation/tree/4.x/packages/drawer).

```bash npm2yarn
npm install react-navigation-drawer
```

## API

```js
import { createDrawerNavigator } from 'react-navigation-drawer';

createDrawerNavigator(RouteConfigs, DrawerNavigatorConfig);
```

### RouteConfigs

The route configs object is a mapping from route name to a route config, which tells the navigator what to present for that route, see [example](stack-navigator.md#routeconfigs) from `createStackNavigator`.

### DrawerNavigatorConfig

- `drawerBackgroundColor` - Use the Drawer background for some color. The Default is `white`.
- `drawerPosition` - Options are `left` or `right`. Default is `left` position.
- `drawerType` - Type of the drawer. It determines how the drawer looks and animates.
  - `front`: Traditional drawer which covers the screen with a overlay behind it.
  - `back`: The drawer is revealed behind the screen on swipe.
  - `slide`: Both the screen and the drawer slide on swipe to reveal the drawer.

- `drawerWidth` - Number or a function which returns the width of the drawer. If a function is provided, it'll be called again when the screen's dimensions change.
- `edgeWidth` - Allows for defining how far from the edge of the content view the swipe gesture should activate
- `hideStatusBar` - when set to true Drawer component will hide the OS status bar whenever the drawer is pulled or when it's in an "open" state.
- `statusBarAnimation` - Animation of the statusbar when hiding it. use in combination with `hideStatusBar`.
- `keyboardDismissMode` - Whether the keyboard should be dismissed when the swipe gesture begins. Defaults to `'on-drag'`. Set to `'none'` to disable keyboard handling.
- `minSwipeDistance` - Minimum swipe distance threshold that should activate opening the drawer.
- `overlayColor` - Color overlay to be displayed on top of the content view when drawer gets open. The opacity is animated from `0` to `1` when the drawer opens.
- `gestureHandlerProps` - Props to pass to the underlying pan gesture handler.
- `lazy` - Whether the screens should render the first time they are accessed. Defaults to `true`. Set it to `false` if you want to render all screens on initial render.
- `unmountInactiveRoutes` - Whether a screen should be unmounted when navigating away from it. Defaults to `false`.
- `contentComponent` - Component used to render the content of the drawer, for example, navigation items. Receives the `navigation` prop and `drawerOpenProgress` for the drawer. Defaults to `DrawerItems`. For more information, see below.
- `contentOptions` - Configure the drawer content, see below.
- `navigationOptions` - Navigation options for the navigator itself, to configure a parent navigator
- `defaultNavigationOptions` - Default navigation options to use for screens

Several options get passed to the underlying router to modify navigation logic:

- `initialRouteName` - The routeName for the initial route.
- `order` - Array of routeNames which defines the order of the drawer items.
- `paths` - Provide a mapping of routeName to path config, which overrides the paths set in the routeConfigs.
- `backBehavior` - Should the back button cause switch to the initial route? If yes, set to `initialRoute`, otherwise `none`. Defaults to `initialRoute` behavior.
- `detachInactiveScreens` - Boolean used to indicate whether inactive screens should be detached from the view hierarchy to save memory. Make sure to call `enableScreens` from [react-native-screens](https://github.com/software-mansion/react-native-screens) to make it work. Defaults to `true`.

### Providing a custom `contentComponent`

The default component for the drawer is scrollable and only contains links for the routes in the RouteConfig. You can easily override the default component to add a header, footer, or other content to the drawer. By default the drawer is scrollable and supports iPhone X safe area. If you customize the content, be sure to wrap the content in a SafeAreaView:

```js
import SafeAreaView from 'react-native-safe-area-view';
import { DrawerItems } from 'react-navigation-drawer';

const CustomDrawerContentComponent = (props) => (
  <ScrollView>
    <SafeAreaView
      style={styles.container}
      forceInset={{ top: 'always', horizontal: 'never' }}
    >
      <DrawerItems {...props} />
    </SafeAreaView>
  </ScrollView>
);

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
});
```

`contentComponent` also received a prop called `drawerOpenProgress` which is an Reanimated Node that represents the animated position of the drawer (0 is closed; 1 is open). This allows you to do interesting animations in your `contentComponent`, such as parallax motion of the drawer contents:

```js
const CustomDrawerContentComponent = (props) => {
  const translateX = Animated.interpolate(drawerOpenProgress, {
    inputRange: [0, 1],
    outputRange: [-100, 0],
  });

  return (
    <Animated.View style={{ transform: [{ translateX }] }}>
      {/* ... drawer contents */}
    </Animated.View>
  );
};
```

### `contentOptions` for `DrawerItems`

- `items` - the array of routes, can be modified or overridden
- `activeItemKey` - key identifying the active route
- `activeTintColor` - label and icon color of the active label
- `activeBackgroundColor` - background color of the active label
- `inactiveTintColor` - label and icon color of the inactive label
- `inactiveBackgroundColor` - background color of the inactive label
- `onItemPress({ route, focused })` - function to be invoked when an item is pressed
- `itemsContainerStyle` - style object for the content section
- `itemStyle` - style object for the single item, which can contain an Icon and/or a Label
- `labelStyle` - style object to overwrite `Text` style inside content section, when your label is a string
- `activeLabelStyle` - style object to overwrite `Text` style of the active label, when your label is a string (merged with `labelStyle`)
- `inactiveLabelStyle` - style object to overwrite `Text` style of the inactive label, when your label is a string (merged with `labelStyle`)
- `iconContainerStyle` - style object to overwrite `View` icon container styles.

#### Example

```js
contentOptions: {
  activeTintColor: '#e91e63',
  itemsContainerStyle: {
    marginVertical: 0,
  },
  iconContainerStyle: {
    opacity: 1
  }
}
```

### Screen Navigation Options

#### `title`

Generic title that can be used as a fallback for `headerTitle` and `drawerLabel`

#### `drawerLabel`

String, React Element or a function that given `{ focused: boolean, tintColor: string }` returns a React.Node, to display in drawer sidebar. When undefined, scene `title` is used

#### `drawerIcon`

React Element or a function, that given `{ focused: boolean, tintColor: string }` returns a React.Node, to display in drawer sidebar

#### `drawerLockMode`

Specifies the lock mode of the drawer. The drawer can be locked in 3 states:

- `unlocked` (default) - that the drawer will respond (open/close) to touch gestures.
- `locked-closed` - that the drawer will stay closed and not respond to gestures.
- `locked-open` - that the drawer will stay opened and not respond to gestures. The drawer may still be opened and closed programmatically with `navigation.openDrawer` and `navigation.closeDrawer`.

### Nesting drawer navigators inside others

If a drawer navigator is nested inside of another navigator that provides some UI, for example a tab navigator or stack navigator, then the drawer will be rendered below the UI from those navigators. The drawer will appear below the tab bar and below the header of the stack. You will need to make the drawer navigator the parent of any navigator where the drawer should be rendered on top of its UI.

---

## createBottomTabNavigator

Source: https://reactnavigation.org/docs/4.x/bottom-tab-navigator

A simple tab bar on the bottom of the screen that lets you switch between different routes. Routes are lazily initialized -- their screen components are not mounted until they are first focused.

To use this navigator, ensure that you have [react-navigation and its dependencies installed](getting-started.md), then install [`react-navigation-tabs`](https://github.com/react-navigation/react-navigation/tree/4.x/packages/tabs).

```bash npm2yarn
npm install react-navigation-tabs
```

## API

```js
import { createBottomTabNavigator } from 'react-navigation-tabs';

createBottomTabNavigator(RouteConfigs, TabNavigatorConfig);
```

> For a complete usage guide please visit [Tab Navigation](tab-based-navigation.md)

## RouteConfigs

The route configs object is a mapping from route name to a route config, which tells the navigator what to present for that route, see [example](stack-navigator.md#routeconfigs) from stack navigator.

## BottomTabNavigatorConfig

- `initialRouteName` - The routeName for the initial tab route when first loading.
- `navigationOptions` - Navigation options for the navigator itself, to configure a parent navigator
- `defaultNavigationOptions` - Default navigation options to use for screens
- `resetOnBlur` - Reset the state of any nested navigators when switching away from a screen. Defaults to `false`.
- `order` - Array of routeNames which defines the order of the tabs.
- `paths` - Provide a mapping of routeName to path config, which overrides the paths set in the routeConfigs.
- `backBehavior` - `initialRoute` to return to initial tab, `order` to return to previous tab, `history` to return to last visited tab, or `none`.
- `detachInactiveScreens` - Boolean used to indicate whether inactive screens should be detached from the view hierarchy to save memory. Make sure to call `enableScreens` from [react-native-screens](https://github.com/software-mansion/react-native-screens) to make it work. Defaults to `true`.
- `lazy` - Defaults to `true`. If `false`, all tabs are rendered immediately. When `true`, tabs are rendered only when they are made active for the first time. Note: tabs are **not** re-rendered upon subsequent visits.
- `tabBarComponent` - Optional, override component to use as the tab bar.
- `tabBarOptions` - An object with the following properties:
  - `activeTintColor` - Label and icon color of the active tab.
  - `activeBackgroundColor` - Background color of the active tab.
  - `inactiveTintColor` - Label and icon color of the inactive tab.
  - `inactiveBackgroundColor` - Background color of the inactive tab.
  - `showLabel` - Whether to show label for tab, default is true.
  - `showIcon` - Whether to show icon for tab, default is true.
  - `style` - Style object for the tab bar.
  - `labelStyle` - Style object for the tab label.
  - `labelPosition` - Where to show the tab label in relation to the tab icon. Available values are `beside-icon` and `below-icon`. Defaults to `below-icon` on mobile and `beside-icon` on tablets.
  - `tabStyle` - Style object for the tab.
  - `allowFontScaling` - Whether label font should scale to respect Text Size accessibility settings, default is true.
  - `adaptive` - Should the tab icons and labels alignment change based on screen size? Defaults to `true` for iOS 11. If `false`, tab icons and labels align vertically all the time. When `true`, tab icons and labels align horizontally on tablet.
  - `safeAreaInset` - Override the `forceInset` prop for `<SafeAreaView>`. Defaults to `{ bottom: 'always', top: 'never' }`. Available keys are `top | bottom | left | right` provided with the values `'always' | 'never'`.
  - `keyboardHidesTabBar` - Defaults to `true`. Hide the tab bar when keyboard opens. Set to `false` to disable this behavior.

Example:

```js
tabBarOptions: {
  activeTintColor: '#e91e63',
  labelStyle: {
    fontSize: 12,
  },
  style: {
    backgroundColor: 'blue',
  },
}
```

If you want to customize the `tabBarComponent`:

```js
import { createBottomTabNavigator, BottomTabBar } from 'react-navigation-tabs';

const TabBarComponent = (props) => <BottomTabBar {...props} />;

const TabScreens = createBottomTabNavigator(
  {
    // other screens
  },
  {
    tabBarComponent: (props) => (
      <TabBarComponent {...props} style={{ borderTopColor: '#605F60' }} />
    ),
  }
);
```

## `navigationOptions` for screens inside of the navigator

#### `title`

Generic title that can be used as a fallback for `headerTitle` and `tabBarLabel`.

#### `tabBarVisible`

`true` or `false` to show or hide the tab bar, if not set then defaults to `true`.

#### `tabBarIcon`

Function that given `{ focused: boolean, horizontal: boolean, tintColor: string }` returns a React.Node, to display in the tab bar. `horizontal` is `true` when the device is in landscape and `false` when portrait. The icon is re-rendered whenever the device orientation changes.

#### `tabBarLabel`

Title string of a tab displayed in the tab bar or a function that given `{ focused: boolean, tintColor: string }` returns a React.Node, to display in tab bar. When undefined, scene `title` is used. To hide, see `tabBarOptions.showLabel` in the previous section.

#### `tabBarButtonComponent`

React Component that wraps the icon and label and implements `onPress`. The default is a wrapper around `TouchableWithoutFeedback` that makes it behave the same as other touchables. `tabBarButtonComponent: TouchableOpacity` would use `TouchableOpacity` instead.

#### `tabBarAccessibilityLabel`

Accessibility label for the tab button. This is read by the screen reader when the user taps the tab. It's recommended to set this if you don't have a label for the tab.

#### `tabBarTestID`

ID to locate this tab button in tests.

#### `tabBarOnPress`

Callback to handle press events; the argument is an object containing:

- `navigation`: navigation prop for the screen
- `defaultHandler`: the default handler for tab press

Useful for adding a custom logic before the transition to the next scene (the
tapped one) starts. When setting tabBarOnPress the defaultHandler needs to be called in order to execute the default action (i.e. switch tab).

#### `tabBarOnLongPress`

Callback to handle long press events; the argument is an object containing:

- `navigation`: navigation prop for the screen
- `defaultHandler`: the default handler for tab press

---

## createMaterialBottomTabNavigator

Source: https://reactnavigation.org/docs/4.x/material-bottom-tab-navigator

A material-design themed tab bar on the bottom of the screen that lets you switch between different routes. Routes are lazily initialized -- their screen components are not mounted until they are first focused.

<img src="/assets/navigators/bottom-navigation.gif" style={{ width: '420px', maxWidth: '100%' }} />

To use this navigator, ensure that you have [react-navigation and its dependencies installed](getting-started.md), then install [`react-navigation-material-bottom-tabs`](https://github.com/react-navigation/react-navigation/tree/4.x/packages/material-bottom-tabs) and [react-native-paper](https://github.com/callstack/react-native-paper).

```bash npm2yarn
npm install react-navigation-material-bottom-tabs react-native-paper
```

This API also requires that you install `react-native-vector-icons`! If you are using Expo (managed or bare), run `npx expo install @expo/vector-icons` instead. Otherwise, [follow these installation instructions](https://github.com/oblador/react-native-vector-icons#installation).

## API

```js
import { createMaterialBottomTabNavigator } from 'react-navigation-material-bottom-tabs';

createMaterialBottomTabNavigator(
  RouteConfigs,
  MaterialBottomTabNavigatorConfig
);
```

This library uses the [`BottomNavigation` component from `react-native-paper`](https://callstack.github.io/react-native-paper/bottom-navigation.html). If you [configure the Babel plugin](https://callstack.github.io/react-native-paper/getting-started.html), it won't include the whole `react-native-paper` library in your bundle.

## RouteConfigs

The route configs object is a mapping from route name to a route config.

## MaterialBottomTabNavigatorConfig

- `shifting` - Whether the shifting style is used, the active tab appears wider and the inactive tabs won't have a label. By default, this is `true` when you have more than 3 tabs.
- `labeled` - Whether to show labels in tabs. When `false`, only icons will be displayed.
- `activeColor` - Custom color for icon and label in the active tab.
- `inactiveColor` - Custom color for icon and label in the inactive tab.
- `barStyle` - Style for the bottom navigation bar. You can set a bottom padding here if you have a translucent navigation bar on Android: `barStyle={{ paddingBottom: 48 }}`.
- `initialRouteName` - The routeName for the initial tab route when first loading.
- `order` - Array of routeNames which defines the order of the tabs.
- `paths` - Provide a mapping of routeName to path config, which overrides the paths set in the routeConfigs.
- `backBehavior` - `initialRoute` to return to initial tab, `order` to return to previous tab, `history` to return to last visited tab, or `none`.

Example:

```js
export default createMaterialBottomTabNavigator(
  {
    Album: { screen: Album },
    Library: { screen: Library },
    History: { screen: History },
    Cart: { screen: Cart },
  },
  {
    initialRouteName: 'Album',
    activeColor: '#f0edf6',
    inactiveColor: '#3e2465',
    barStyle: { backgroundColor: '#694fad' },
  }
);
```

## `navigationOptions` for screens inside of the navigator

#### `title`

Generic title that can be used as a fallback for `headerTitle` and `tabBarLabel`.

#### `tabBarIcon`

React Element or a function that given `{ focused: boolean, horizontal: boolean, tintColor: string }` returns a React.Node, to display in the tab bar. `horizontal` is `true` when the device is in landscape and `false` when portrait. The icon is re-rendered whenever the device orientation changes.

#### `tabBarColor`

Color for the tab bar when the tab corresponding to the screen is active. Used for the ripple effect. This is only supported when `shifting` is `true`.

#### `tabBarLabel`

Title string of a tab displayed in the tab bar. When undefined, scene `title` is used. To hide, see `labeled` option in the previous section.

#### `tabBarBadge`

Badge to show on the tab icon, can be `true` to show a dot, `string` or `number` to show text.

#### `tabBarAccessibilityLabel`

Accessibility label for the tab button. This is read by the screen reader when the user taps the tab. It's recommended to set this if you don't have a label for the tab.

#### `tabBarTestID`

ID to locate this tab button in tests.

#### `tabBarOnPress`

Callback to handle press events; the argument is an object containing:

- `navigation`: navigation prop for the screen
- `defaultHandler`: the default handler for tab press

Useful for adding a custom logic before the transition to the next scene (the tapped one) starts. When setting tabBarOnPress the defaultHandler needs to be called in order to execute the default action (i.e. switch tab).

## Using with `react-native-paper` (optional)

You can use the theming support in `react-native-paper` to customize the material bottom navigation by wrapping your app in [`Provider` from `react-native-paper`](https://callstack.github.io/react-native-paper/getting-started.html). A common use case for this can be to customize the background color for the screens when your app has a dark theme. Follow the [instructions on `react-native-paper`'s documentation](https://callstack.github.io/react-native-paper/theming.html) to learn how to customize the theme.

---

## createMaterialTopTabNavigator

Source: https://reactnavigation.org/docs/4.x/material-top-tab-navigator

A material-design themed tab bar on the top of the screen that lets you switch between different routes by tapping the route or swiping horizontally. Transitions are animated by default. Screen components for each route are mounted immediately.

To use this navigator, ensure that you have [react-navigation and its dependencies installed](getting-started.md), then install [`react-navigation-tabs`](https://github.com/react-navigation/react-navigation/tree/4.x/packages/tabs).

```bash npm2yarn
npm install react-navigation-tabs
```

## API

```js
import { createMaterialTopTabNavigator } from 'react-navigation-tabs';

createMaterialTopTabNavigator(RouteConfigs, TabNavigatorConfig);
```

## RouteConfigs

The route configs object is a mapping from route name to a route config.

## TabNavigatorConfig

### `initialRouteName`

The routeName for the initial tab route when first loading.

### `navigationOptions`

Navigation options for the navigator itself, to configure a parent navigator

### `defaultNavigationOptions`

Default navigation options to use for screens

### `order`

Array of routeNames which defines the order of the tabs.

### `paths`

Provide a mapping of routeName to path config, which overrides the paths set in the routeConfigs.

### `backBehavior`

Pass `initialRoute` to return to initial tab, `order` to return to previous tab, `history` to return to last visited tab, or `none`.

### `tabBarPosition`

Position of the tab bar, can be `'top'` or `'bottom'`, default is `top`.

### `swipeEnabled`

Whether to allow swiping between tabs.

### `lazy`

Defaults to `false`. If `true`, tabs are rendered only when they are made active or on peek swipe. When `false`, all tabs are rendered immediately.

### `lazyPlaceholderComponent`

React component to render for routes that haven't been rendered yet. Receives an object containing the route as the argument. The `lazy` prop also needs to be enabled.

### `initialLayout`

Optional object containing the initial `height` and `width`, can be passed to prevent the one frame delay in [react-native-tab-view](https://github.com/react-navigation/react-navigation/tree/main/packages/react-native-tab-view#avoid-one-frame-delay) rendering.

### `pagerComponent`

React component to use as the pager. The pager handles swipe gestures and page switching. By default we use [`react-native-gesture-handler`](https://github.com/software-mansion/react-native-gesture-handler) for handling gestures. You can switch out the pager for a different implementation to customize the experience.

For example, to use pager backed by the native `ViewPager`, you can use [`react-native-tab-view-viewpager-adapter`](https://github.com/software-mansion/react-native-tab-view-viewpager-adapter):

```js
import ViewPagerAdapter from 'react-native-tab-view-viewpager-adapter';

// ...

const Tabs = createMaterialTopTabNavigator(
  {
    // routes
  },
  {
    pagerComponent: ViewPagerAdapter,
  }
);
```

### `tabBarComponent`

Optional, override the component to use as the tab bar.

### `tabBarOptions`

An object with the following properties:

- `activeTintColor` - Label and icon color of the active tab.
- `inactiveTintColor` - Label and icon color of the inactive tab.
- `showIcon` - Whether to show icon for tab, default is false.
- `showLabel` - Whether to show label for tab, default is true.
- `upperCaseLabel` - Whether to make label uppercase, default is true.
- `pressColor` - Color for material ripple (Android >= 5.0 only).
- `pressOpacity` - Opacity for pressed tab (iOS and Android < 5.0 only).
- `scrollEnabled` - Whether to enable scrollable tabs.
- `tabStyle` - Style object for the tab.
- `indicatorStyle` - Style object for the tab indicator (line at the bottom of the tab).
- `labelStyle` - Style object for the tab label.
- `iconStyle` - Style object for the tab icon.
- `style` - Style object for the tab bar.
- `allowFontScaling` - Whether label font should scale to respect Text Size accessibility settings, default is true.
- `renderIndicator` - Function which takes an object with the current route and returns a custom React Element to be used as a tab indicator.

These options are passed as props to the tab bar component.

Example:

```js
tabBarOptions: {
  labelStyle: {
    fontSize: 12,
  },
  tabStyle: {
    width: 100,
  },
  style: {
    backgroundColor: 'blue',
  },
}
```

## `navigationOptions` for screens inside of the navigator

#### `title`

Generic title that can be used as a fallback for `headerTitle` and `tabBarLabel`.

#### `swipeEnabled`

True or false to enable or disable swiping between tabs, if not set then defaults to TabNavigatorConfig option swipeEnabled.

#### `tabBarIcon`

React Element or a function that given `{ focused: boolean, horizontal: boolean, tintColor: string }` returns a React.Node, to display in the tab bar. `horizontal` is `true` when the device is in landscape and `false` when portrait. The icon is re-rendered whenever the device orientation changes.

#### `tabBarLabel`

Title string of a tab displayed in the tab bar or React Element or a function that given `{ focused: boolean, tintColor: string }` returns a React.Node, to display in tab bar. When undefined, scene `title` is used. To hide, see `tabBarOptions.showLabel` in the previous section.

#### `tabBarAccessibilityLabel`

Accessibility label for the tab button. This is read by the screen reader when the user taps the tab. It's recommended to set this if you don't have a label for the tab.

#### `tabBarTestID`

ID to locate this tab button in tests.

#### `tabBarOnPress`

Callback to handle press events; the argument is an object containing:

- `navigation`: navigation prop for the screen
- `defaultHandler`: the default handler for tab press

Useful for adding a custom logic before the transition to the next scene (the
tapped one) starts. When setting tabBarOnPress the defaultHandler needs to be called in order to execute the default action (i.e. switch tab).

#### `tabBarOnLongPress`

Callback to handle long press events; the argument is an object containing:

- `navigation`: navigation prop for the screen
- `defaultHandler`: the default handler for tab press

---

## NavigationActions reference

Source: https://reactnavigation.org/docs/4.x/navigation-actions

All `NavigationActions` return an object that can be sent to the router using `navigation.dispatch()` method.

Note that if you want to dispatch react-navigation actions you should use the action creators provided in this library.

It's important to highlight that dispatching a `NavigationAction` doesn't throw any error when the action is unhandled (similar to when you dispatch an action that isn't handled by a reducer in redux and nothing happens). However, if the app state changes as a result of a dispatch then the return value of the dispatch is `true` and `false` otherwise.

The following actions are supported:

- [Navigate](#navigate) - Navigate to another route
- [Back](#back) - Go back to previous state
- [Set Params](#setparams) - Set Params for given route

For actions specific to a StackNavigator, see [StackActions](stack-actions.md).
For actions specific to a switch-based navigators such as TabNavigator, see [SwitchActions](switch-actions.md).

The action creator functions define `toString()` to return the action type, which enables easy usage with third-party Redux libraries, including redux-actions and redux-saga.

### navigate

The `navigate` action will update the current state with the result of a `navigate` action.

- `routeName` - _String_ - Required - A destination routeName that has been registered somewhere in the app's router
- `params` - _Object_ - Optional - Params to merge into the destination route
- `action` - _Object_ - Optional - (advanced) The sub-action to run in the child router, if the screen is a navigator. Any one of the actions described in this doc can be set as a sub-action.
- `key` - _String_ - Optional - The identifier for the route to navigate to. Navigate back to this route if it already exists

```js
import { NavigationActions } from 'react-navigation';

const navigateAction = NavigationActions.navigate({
  routeName: 'Profile',

  params: {},

  action: NavigationActions.navigate({ routeName: 'SubProfileRoute' }),
});

this.props.navigation.dispatch(navigateAction);
```

### back

Go back to previous screen and close current screen. `back` action creator takes in one optional parameter:

- `key` - _string or null_ - optional - If set, navigation will go back from the given key. If null, navigation will go back anywhere.

```js
import { NavigationActions } from 'react-navigation';

const backAction = NavigationActions.back({
  key: 'Profile',
});
this.props.navigation.dispatch(backAction);
```

### setParams

When dispatching `setParams`, the router will produce a new state that has changed the params of a particular route, as identified by the key

- `params` - _object_ - required - New params to be merged into existing route params
- `key` - _string_ - required - Route key that should get the new params

```js
import { NavigationActions } from 'react-navigation';

const setParamsAction = NavigationActions.setParams({
  params: { title: 'Hello' },
  key: 'screen-123',
});
this.props.navigation.dispatch(setParamsAction);
```

---

## StackActions reference

Source: https://reactnavigation.org/docs/4.x/stack-actions

`StackActions` is an object containing methods for generating actions specific to stack-based navigators. Its methods expand upon the actions available in [`NavigationActions`](navigation-actions.md).

The following actions are supported:

- [Reset](#reset) - Replace current state with a new state
- [Replace](#replace) - Replace a route at a given key with another route
- [Push](#push) - Add a route on the top of the stack, and navigate forward to it
- [Pop](#pop) - Navigate back to previous routes
- [PopToTop](#poptotop) - Navigate to the top route of the stack, dismissing all other routes

### reset

The `reset` action wipes the whole navigation state and replaces it with the result of several actions.

- `index` - _number_ - required - Index of the active route on `routes` array in navigation `state`.
- `actions` - _array_ - required - Array of Navigation Actions that will replace the navigation state.
- `key` - _string or null_ - optional - If set, the navigator with the given key will reset. If null, the root navigator will reset.

```js
import { StackActions, NavigationActions } from 'react-navigation';

const resetAction = StackActions.reset({
  index: 0,
  actions: [NavigationActions.navigate({ routeName: 'Profile' })],
});
this.props.navigation.dispatch(resetAction);
```

#### How to use the `index` parameter

The `index` param is used to specify the current active route.

eg: given a basic stack navigation with two routes `Profile` and `Settings`.
To reset the state to a point where the active screen was `Settings` but have it stacked on top of a `Profile` screen, you would do the following:

```js
import { StackActions, NavigationActions } from 'react-navigation';

const resetAction = StackActions.reset({
  index: 1,
  actions: [
    NavigationActions.navigate({ routeName: 'Profile' }),
    NavigationActions.navigate({ routeName: 'Settings' }),
  ],
});
this.props.navigation.dispatch(resetAction);
```

### replace

The `replace` action replaces the route at the given key with another route.

- `key` - _string_ - Key of the route to replace. If this is not defined, the most recent route will be replaced.
- `newKey` - _string_ - Key to use for the replacement route. Generated automatically if not provided.
- `routeName` - _string_ - `routeName` to use for replacement route.
- `params` - _object_ - Parameters to pass in to the replacement route.
- `action` - _object_ - Optional sub-action.

### push

The `push` action adds a route on top of the stack and navigates forward to it. This differs from `navigate` in that `navigate` will pop back to earlier in the stack if a route of the given name is already present there. `push` will always add on top, so a route can be present multiple times.

- `routeName` - _string_ - `routeName` to push onto the stack.
- `params` - _object_ - Screen params to merge into the destination route (found in the pushed screen through `this.props.navigation.state.params`).
- `action` - (advanced) The sub-action to run in the child router, if the screen is a navigator.

```js
import { StackActions } from 'react-navigation';

const pushAction = StackActions.push({
  routeName: 'Profile',
  params: {
    myUserId: 9,
  },
});

this.props.navigation.dispatch(pushAction);
```

### pop

The `pop` action takes you back to a previous screen in the stack. The `n` param allows you to specify how many screens to pop back by.

- `n` - _number_ - The number of screens to pop back by.

```js
import { StackActions } from 'react-navigation';

const popAction = StackActions.pop({
  n: 1,
});

this.props.navigation.dispatch(popAction);
```

### popToTop

The `popToTop` action takes you back to the first screen in the stack, dismissing all the others. It's functionally identical to `StackActions.pop({n: currentIndex})`.

```js
import { StackActions } from 'react-navigation';

this.props.navigation.dispatch(StackActions.popToTop());
```

---

## SwitchActions reference

Source: https://reactnavigation.org/docs/4.x/switch-actions

`SwitchActions` is an object containing methods for generating actions specific to switch-based navigators. Its methods expand upon the actions available in [`NavigationActions`](navigation-actions.md).

The following actions are supported:

- [JumpTo](#jumpto) - Jump to a route in the navigator

### jumpTo

The `jumpTo` action can be used to jump to an existing route in the switch navigator.

- `routeName` - _string_ - required - `routeName` of the route to jump to.
- `key` - _string_ - optional - If set, the action will be scoped to the switch-based navigator with the given key.

```js
import { SwitchActions } from 'react-navigation';

this.props.navigation.dispatch(SwitchActions.jumpTo({ routeName }));
```

---

## DrawerActions reference

Source: https://reactnavigation.org/docs/4.x/drawer-actions

`DrawerActions` is an object containing methods for generating actions specific to drawer-based navigators. Its methods expand upon the actions available in [`NavigationActions`](navigation-actions.md).

The following actions are supported:

- openDrawer - open the drawer
- closeDrawer - close the drawer
- toggleDrawer - toggle the state, ie. switches from closed to open and vice versa

### Usage

```js
import { DrawerActions } from 'react-navigation-drawer';

this.props.navigation.dispatch(DrawerActions.toggleDrawer());
```

---

## withNavigation

Source: https://reactnavigation.org/docs/4.x/with-navigation

`withNavigation` is a higher order component which passes the `navigation` prop into a wrapped component. It's useful when you cannot pass the `navigation` prop into the component directly, or don't want to pass it in case of a deeply nested child.

- `withNavigation(Component)` returns a Component.

## Example

```js
import React from 'react';
import { Button } from 'react-native';
import { withNavigation } from 'react-navigation';

class MyBackButton extends React.Component {
  render() {
    return (
      <Button
        title="Back"
        onPress={() => {
          this.props.navigation.goBack();
        }}
      />
    );
  }
}

// withNavigation returns a component that wraps MyBackButton and passes in the
// navigation prop
export default withNavigation(MyBackButton);
```

## Notes

- If you wish to use the `ref` prop on the wrapped component, you must pass the `onRef` prop instead. For example,

```js
// MyBackButton.ts
export default withNavigation(MyBackButton);

// MyNavBar.ts
<MyBackButton onRef={(elem) => (this.backButton = elem)} />;
```

---

## withNavigationFocus

Source: https://reactnavigation.org/docs/4.x/with-navigation-focus

`withNavigationFocus` is a higher order component which passes the `isFocused` prop into a wrapped component. It's useful if you need to use the focus state in the render function of your screen component or another component rendered somewhere inside of a screen.

- `withNavigationFocus(Component)` returns a component.

## Example

```js
import React from 'react';
import { Text } from 'react-native';
import { withNavigationFocus } from 'react-navigation';

class FocusStateLabel extends React.Component {
  render() {
    return <Text>{this.props.isFocused ? 'Focused' : 'Not focused'}</Text>;
  }
}

// withNavigationFocus returns a component that wraps FocusStateLabel and passes
// in the navigation prop
export default withNavigationFocus(FocusStateLabel);
```

---

## Scrollables

Source: https://reactnavigation.org/docs/4.x/scrollables

React Navigation exports its own `ScrollView`, `FlatList`, and `SectionList`. The built-in components are wrapped in order to respond to events from navigation that will scroll to top when tapping on the active tab as you would expect from native tab bars.

Example

```jsx harmony
import React from 'react';
import { Text, View } from 'react-native';
import { createAppContainer, FlatList } from 'react-navigation';
import { createBottomTabNavigator } from 'react-navigation-tabs';

const data = new Array(150).fill(0);

class HomeScreen extends React.Component {
  renderItem = ({ index }) => {
    return (
      <View style={{ height: 50 }}>
        <Text style={{ textAlign: 'center' }}>Item {index}</Text>
      </View>
    );
  };

  render() {
    return (
      <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
        <FlatList
          data={data}
          renderItem={this.renderItem}
          contentContainerStyle={{ padding: 10 }}
        />
      </View>
    );
  }
}

const TabNavigator = createBottomTabNavigator({
  Home: { screen: HomeScreen },
});

export default createAppContainer(TabNavigator);
```

<a href="https://snack.expo.io/@react-navigation/basic-scrollables-tab-v3" target="blank" class="run-code-button">&rarr; Run this code</a>

---

## Overview

Source: https://reactnavigation.org/docs/4.x/custom-navigator-overview

Navigators allow you to define your application's navigation structure. Navigators also render common elements such as headers and tab bars which you can configure.

Under the hood, navigators are plain React components.

## Built-in Navigators

`react-navigation` includes some commonly needed navigators such as:

- [createStackNavigator](stack-navigator.md) - Renders one screen at a time and provides transitions between screens. When a new screen is opened it is placed on top of the stack.
- [`createBottomTabNavigator`](bottom-tab-navigator.md) - Renders a tab bar that lets the user switch between several screens.
- [createSwitchNavigator](switch-navigator.md) - Switch between one screen and another with no UI on top of it, unmount screens when they become inactive.
- [createDrawerNavigator](drawer-navigator.md) - Provides a drawer that slides in from the left of the screen.

## Rendering screens with Navigators

The navigators render application screens which are just React components.

To learn how to create screens, read about:

- [Screen `navigation` prop](navigation-prop.md) to allow the screen to dispatch navigation actions, such as opening another screen
- Screen `navigationOptions` to customize how the screen gets presented by the navigator (e.g. [header title](stack-navigator.md#navigationoptions-for-screens-inside-of-the-navigator), tab label)

---

## Routers

Source: https://reactnavigation.org/docs/4.x/routers

Routers define a component's navigation state, and they allow the developer to define paths and actions that can be handled.

## Built-In Routers

`react-navigation` ships with a few standard routers:

- [StackRouter](https://github.com/react-navigation/react-navigation/blob/4.x/packages/core/src/routers/StackRouter.js)
- [TabRouter](https://github.com/react-navigation/react-navigation/blob/4.x/packages/core/src/routers/TabRouter.js)

## Using Routers

To make a navigator manually, put a static `router` on a component.

```js
class MyNavigator extends React.Component {
  static router = StackRouter(routes, config);
  ...
}
```

Now you can use this component as a `screen` in another navigator, and the navigation logic for `MyNavigator` will be defined by this `StackRouter`.

## Customizing Routers

See the [Custom Router API spec](custom-routers.md) to learn about the API of `StackRouter` and `TabRouter`. You can override the router functions as you see fit:

### Custom Navigation Actions

To override navigation behavior, you can override the navigation state logic in `getStateForAction`, and manually manipulate the `routes` and `index`.

```js
const MyApp = createStackNavigator(
  {
    Home: { screen: HomeScreen },
    Profile: { screen: ProfileScreen },
  },
  {
    initialRouteName: 'Home',
  }
);

const defaultGetStateForAction = MyApp.router.getStateForAction;

MyApp.router.getStateForAction = (action, state) => {
  if (state && action.type === 'PushTwoProfiles') {
    const routes = [
      ...state.routes,
      { key: 'A', routeName: 'Profile', params: { name: action.name1 } },
      { key: 'B', routeName: 'Profile', params: { name: action.name2 } },
    ];
    return {
      ...state,
      routes,
      index: routes.length - 1,
    };
  }
  return defaultGetStateForAction(action, state);
};
```

### Blocking Navigation Actions

Sometimes you may want to prevent some navigation activity, depending on your route.

```js
import { NavigationActions } from 'react-navigation';

const MyStackRouter = StackRouter(
  {
    Home: { screen: HomeScreen },
    Profile: { screen: ProfileScreen },
  },
  {
    initialRouteName: 'Home',
  }
);

const defaultGetStateForAction = MyStackRouter.router.getStateForAction;

MyStackRouter.router.getStateForAction = (action, state) => {
  if (
    state &&
    action.type === NavigationActions.BACK &&
    state.routes[state.index].params.isEditing
  ) {
    // Returning null from getStateForAction means that the action
    // has been handled/blocked, but there is not a new state
    return null;
  }

  return defaultGetStateForAction(action, state);
};
```

### Handling Custom URIs

Perhaps your app has a unique URI which the built-in routers cannot handle. You can always extend the router `getActionForPathAndParams`.

```js
import { NavigationActions } from 'react-navigation';

const MyApp = createStackNavigator(
  {
    Home: { screen: HomeScreen },
    Profile: { screen: ProfileScreen },
  },
  {
    initialRouteName: 'Home',
  }
);
const previousGetActionForPathAndParams =
  MyApp.router.getActionForPathAndParams;

Object.assign(MyApp.router, {
  getActionForPathAndParams(path, params) {
    if (path === 'my/custom/path' && params.magic === 'yes') {
      // returns a profile navigate action for /my/custom/path?magic=yes
      return NavigationActions.navigate({
        routeName: 'Profile',
        action: NavigationActions.navigate({
          // This child action will get passed to the child router
          // ProfileScreen.router.getStateForAction to get the child
          // navigation state.
          routeName: 'Friends',
        }),
      });
    }
    return previousGetActionForPathAndParams(path, params);
  },
});
```

---

## Custom navigators

Source: https://reactnavigation.org/docs/4.x/custom-navigators

A navigator is any React component that has a [router](https://github.com/react-navigation/react-navigation/tree/4.x/packages/core/src/routers/StackRouter.js) on it, to define the navigation behavior. Each navigator is given a `navigation` prop, which allows the parent to control the navigation state.

## Extending Navigators

It is possible to take an existing Navigator and extend its behavior, using the following approach:

```js
const MyStack = createStackNavigator({ ... });

class CustomNavigator extends React.Component {
  static router = MyStack.router;
  render() {
    const { navigation } = this.props;

    return <MyStack navigation={navigation} />;
  }
}
```

Now it is possible to render additional things, observe the navigation prop, and override behavior of the router:

```js
const MyStack = createStackNavigator({ ... });

class CustomNavigator extends React.Component {
  static router = {
    ...MyStack.router,
    getStateForAction: (action, lastState) => {
      // check for custom actions and return a different navigation state.
      return MyStack.router.getStateForAction(action, lastState);
    },
  };
  componentDidUpdate(lastProps) {
    // Navigation state has changed from lastProps.navigation.state to this.props.navigation.state
  }
  render() {
    const { navigation } = this.props;

    return (
      <View>
        <MyStack navigation={navigation} />
        {...}
      </View>
    );
  }
}
```

## Navigator Navigation Prop

The navigation prop passed down to a navigator only includes `state`, `dispatch`, and `addListener`. This is the current state of the navigator, and an event channel to send action requests.

All navigators are controlled components: they always display what is coming in through `props.navigation.state`, and their only way to change the state is to send actions into `props.navigation.dispatch`.

Navigators can specify custom behavior to parent navigators by [customizing their router](custom-routers.md). For example, a navigator is able to specify when actions should be blocked by returning null from `router.getStateForAction`. Or a navigator can specify custom URI handling by overriding `router.getActionForPathAndParams` to output a relevant navigation action, and handling that action in `router.getStateForAction`.

### Navigation State

The navigation state that is passed into a navigator's `props.navigation.state` has the following structure:

```
{
  index: 1, // identifies which route in the routes array is active
  routes: [
    {
      // Each route needs a name, which routers will use to associate each route
      // with a react component
      routeName: 'MyRouteName',

      // A unique id for this route, used to keep order in the routes array:
      key: 'myroute-123',

      // Routes can have any additional data. The included routers have `params`
      ...customRouteData,
    },
    ...moreRoutes,
  ]
}
```

### Navigation Dispatchers

A navigator can dispatch navigation actions, such as 'Go to a URI', 'Go back'.

The dispatcher will return `true` if the action was successfully handled, otherwise `false`.

## API for building custom navigators

To help developers implement custom navigators, the following utilities are provided with React Navigation:

### `createNavigator`

> Note: The `createNavigator` API has changed in version 2. The old doc for v1 can be accessed here: [v1.reactnavigation.org/docs/custom-navigators.html](https://v1.reactnavigation.org/docs/custom-navigators.html)

This utility combines a [router](routers.md) and a [navigation view](navigation-views.md) together in a standard way:

```js
import { createNavigator } from 'react-navigation';

const AppNavigator = createNavigator(NavigationView, router, navigationConfig);
```

The new `AppNavigator` can be rendered as such:

```js
<AppNavigator
  navigation={{ state, dispatch, addListener }}
  screenProps={...}
/>
```

Then the view will be rendered in the following way:

```js
<NavigationView
  screenProps={screenProps}
  navigation={navigation}
  navigationConfig={navigationConfig}
  descriptors={descriptors}
/>
```

The `navigation` prop is the same navigation prop that was passed into the navigator.

Both `navigationConfig` and `screenProps` are simply passed through, as defined above.

Most information about child screens comes through the `descriptors` prop. The descriptors is an object map of route keys to scene descriptors. There is one descriptor for each child route.

### Scene Descriptors

A scene descriptor has the following properties:

- `getComponent`, a function that returns the component for the screen
- `options`, the flattened navigationOptions for the route
- `navigation`, the child navigation prop, including actions and the route `state`
- `state`, the navigation state for the child screen (a shortcut for `navigation.state`)
- `key`, the key of the route (a shortcut for `navigation.state.key`)

---

## Custom routers

Source: https://reactnavigation.org/docs/4.x/custom-routers

You can make your own router by building an object with the following functions:

```js
const MyRouter = {
  getStateForAction: (action, state) => ({}),
  getActionForPathAndParams: (path, params) => null,
  getPathAndParamsForState: (state) => null,
  getComponentForState: (state) => MyScreen,
  getComponentForRouteName: (routeName) => MyScreen,
};

// Now, you can make a navigator by putting the router on it:
class MyNavigator extends React.Component {
  static router = MyRouter;
  render() {
    ...
  }
}
```

![Routers manage the relationship between URIs, actions, and navigation state](/assets/routers/routers-concept-map.png)

### `getStateForAction(action, state)`

Defines the navigation state in response to a given action. This function will be run when an action gets passed into `props.navigation.dispatch(`, or when any of the helper functions are called, like `navigation.navigate(`.

Typically this should return a navigation state, with the following form:

```
{
  index: 1, // identifies which route in the routes array is active
  routes: [
    {
      // Each route needs a name to identify the type.
      routeName: 'MyRouteName',

      // A unique identifier for this route in the routes array:
      key: 'myroute-123',
      // (used to specify the re-ordering of routes)

      // Routes can have any data, as long as key and routeName are correct
      ...randomRouteData,
    },
    ...moreRoutes,
  ]
}
```

If the router has handled the action externally, or wants to swallow it without changing the navigation state, this function will return `null`.

### `getComponentForRouteName(routeName)`

Returns the child component or navigator for the given route name.

Say a router `getStateForAction` outputs a state like this:

```js
{
  index: 1,
  routes: [
    { key: 'A', routeName: 'Foo' },
    { key: 'B', routeName: 'Bar' },
  ],
}
```

Based on the routeNames in the state, the router is responsible for returning valid components when calling `router.getComponentForRouteName('Foo')` or `router.getComponentForRouteName('Bar')`.

### `getComponentForState(state)`

Returns the active component for a deep navigation state.

### `getActionForPathAndParams(path, params)`

Returns an optional navigation action that should be used when the user navigates to this path and provides optional query parameters.

### `getPathAndParamsForState(state)`

Returns the path and params that can be put into the URL to link the user back to the same spot in the app.

The path/params that are output from this should form an action when passed back into the router's `getActionForPathAndParams`. That action should take you to a similar state once passed through `getStateForAction`.

### `getScreenOptions(navigation, screenProps)`

Used to retrieve the navigation options for a screen. Must provide the screen's current navigation prop and optionally, other props that your navigation options may need to consume.

- `navigation` - This is the navigation prop that the screen will use, where the state refers to the screen's route/state. Dispatch will trigger actions in the context of that screen.
- `screenProps` - Other props that your navigation options may need to consume
- `navigationOptions` - The previous set of options that are default or provided by the previous configurer

Inside an example view, perhaps you need to fetch the configured title:

```js
// First, prepare a navigation prop for your child, or re-use one if already available.
const screenNavigation = addNavigationHelpers({
  // In this case we use navigation.state.index because we want the title for the active route.
  state: navigation.state.routes[navigation.state.index],
  dispatch: navigation.dispatch,
});
const options = this.props.router.getScreenOptions(screenNavigation, {});
const title = options.title;
```

---

## Navigation views

Source: https://reactnavigation.org/docs/4.x/navigation-views

Navigation views are presentation components that take a [`router`](routers.md) and a [`navigation`](navigation-prop.md) prop, and can display several screens, as specified by the `navigation.state`.

Navigation views are controlled React components that can present the current navigation state. They manage switching of screens, animations and gestures. They also present persistent navigation views such as tab bars and headers.

## Built in Views

- [StackView](https://github.com/react-navigation/react-navigation/blob/4.x/packages/stack/src/views/StackView.tsx) - Present a stack that looks suitable on any platform
  - [StackViewCard](https://github.com/react-navigation/stack/blob/1.0/src/views/StackView/StackViewCard.tsx) - Present one card from the card stack, with gestures
  - [Header](https://github.com/react-navigation/stack/blob/1.0/src/views/Header/Header.tsx) - The header view for the card stack
- [SwitchView](https://github.com/react-navigation/react-navigation/blob/4.x/packages/core/src/views/SwitchView/SwitchView.js) - A navigator that only ever show one screen at a time, useful for authentication flows.
- [Tabs](https://github.com/react-navigation/react-navigation/tree/4.x/packages/tabs) - A configurable tab switcher / pager
- [Drawer](https://github.com/react-navigation/react-navigation/tree/4.x/packages/drawer) - A view with a drawer that slides from the left

---

## Supported React Native versions

Source: https://reactnavigation.org/docs/4.x/supported-react-native-versions

Since `react-navigation@3.x` depends on the new `React.createContext` API, which was added in `react@16.3.x`, we require `react-native@^0.54.x`. Also, `react-navigation@3.x` needs [react-native-gesture-handler](https://github.com/software-mansion/react-native-gesture-handler#react-native-support) to work, so you will need to make sure that the version of `react-native-gesture-handler` you are using matches your current `react-native` version.

If you are using [react-native-screens](react-native-screens.md), you will need to be aware of its own supported `react-native` version too.

> Please note that the statements above may not be correct for a particular `react-native` version. If you notice a version that is not working properly, feel free to either file an [issue](https://github.com/react-navigation/react-navigation.github.io/issues/new) or correct it in this page.

---

## Community-developed Navigators and Libraries

Source: https://reactnavigation.org/docs/4.x/community-libraries-and-navigators

# Navigators

## Fluid Transitions

Fluid Transitions is a library that provides Shared Element Transitions during navigation between screens using react-navigation.

A Shared Element Transition is the visualization of an element in one screen being transformed into a corresponding element in another screen during the navigation transition.

The library implements a custom navigator called `FluidNavigator` that makes all this and more possible.

#### Links

[github.com/fram-x/FluidTransitions](https://github.com/fram-x/FluidTransitions)

# Libraries

## react-navigation-collapsible

react-navigation-collapsible is a library and a `Higher Order Component` that adjusts your navigationOptions and makes your screen header collapsible.

Since react-navigation's header is designed as `Animated` component, you can animate the header by passing `Animated.Value` from your `ScrollView` or `FlatList` to the header.

#### Links

[github.com/benevbright/react-navigation-collapsible](https://github.com/benevbright/react-navigation-collapsible)

[Demo on Snack](https://snack.expo.io/@benevbright/react-navigation-collapsible)

## react-native-screens

This project aims to expose native navigation container components to React Native and React Navigation can integrate with it since version 2.14.0. Using `react-native-screens` brings several benefits, such as support for the ["reachability feature"](https://www.cnet.com/how-to/how-to-use-reachability-on-iphone-6-6-plus/) on iOS, and improved memory consumption on both platforms.

#### Links

[github.com/software-mansion/react-native-screens](https://github.com/software-mansion/react-native-screens)

## react-navigation-header-buttons

Helps you to render buttons in the navigation bar and handle the styling so you don't have to. It tries to mimic the appearance of native navbar buttons and attempts to offer a simple interface for you to interact with.

#### Links

[github.com/vonovak/react-navigation-header-buttons](https://github.com/vonovak/react-navigation-header-buttons)

[Demo on expo](https://expo.io/@vonovak/navbar-buttons-demo)

## react-navigation-props-mapper

Provides simple HOCs that map react-navigation props to your screen components directly - ie. instead of `const user = this.props.navigation.getParam(activeUser, null)`, you'd write `const user = this.props.activeUser`.

## react-native-header-scroll-view

This component implements [iOS large header with grow/shrink on scroll](https://react-navigation.canny.io/feature-requests/p/ios-11-large-header-and-growshrink-on-scroll), made by [@jonsamp](https://github.com/jonsamp). Note that it doesn't handle header animation between screens, it only handles animating the header title on scroll.

To use this component, we'd want to disable the built-in header. There are 2 ways to disable the header in React Navigation:

1. Disable the default header for one screen:

```js
static navigationOptions = {
  headerShown: false
};
```

2. Disable header globally in `createStackNavigator`

```js
const Home = createStackNavigator(
  {
    ExampleScreen1,
    ExampleScreen1,
  },
  {
    headerMode: 'none',
  }
);
```

#### Links

[github.com/vonovak/react-navigation-props-mapper](https://github.com/vonovak/react-navigation-props-mapper)

---

## More Resources

Source: https://reactnavigation.org/docs/4.x/more-resources

# Talks

- [Mobile App Development with React Native at Harvard Extension School](https://cs50.harvard.edu/mobile/2018/): Lecture 6 covers React Navigation, includes exercises, slides, and video.

- [Mobile Navigation at React Alicante](https://www.youtube.com/watch?v=GBhdooVxX6Q): An overview and comparison of the approaches taken by react-native-navigation and react-navigation.

- [Owning Transitions at React Native EU](https://www.youtube.com/watch?v=1LKqGx3z0W4): Discusses a new transitioner API and how to use it.

- [It all starts with navigation at React Native EU](https://www.youtube.com/watch?v=Z0Jl1KCWiag): Explains the evolution of React Native navigation libraries over time and the problems that required building native APIs to solve and what those solutions were.

- [React Navigation at React Amsterdam](https://www.youtube.com/watch?v=wJJZ9Od8MjM): An introduction to React Navigation.

---

## Pitch & anti-pitch

Source: https://reactnavigation.org/docs/4.x/pitch

It's useful when considering whether or not to use a project to understand the tradeoffs that the developers of the project made when building it. What problems does it explicitly try to solve for you, and which ones does it ignore? What are the current limitations of the project and common problems that people encounter? These are the kinds of questions that we believe you should have answers to when making an important technology decision for your project, and so we have documented answers to these questions as best we can here, in the form of a "pitch" (why you should use it) and "anti-pitch" (why you should not use it). Please [submit a pull request](https://github.com/react-navigation/website) if you believe we have omitted important information!

## Pitch

- Everything is written in JavaScript on top of React Native primitives &mdash; for example, animations use the `Animated` API and its native driver option in order to run the animations on the main thread and produce smooth 60 fps transitions. Writing everything except the low-level primitives like animations and gestures in JavaScript has a lot of benefits:
  - Easy OTA updates
  - Debuggable
  - Customizable
- Most apps heavily customize navigation, to do this with an API that wraps native navigation you will need to write a lot of native code.
- It's easy to write your own navigators that integrate cleanly with standard navigators, or to fork the standard navigators and create your own version of them with the exact look and feel you want in your app.

## Anti-pitch

- The API is sometimes unintuitive and difficult to use, improvements may require breaking changes. We are working to make ["easy things easy and hard things possible"](https://www.quora.com/What-is-the-origin-of-the-phrase-make-the-easy-things-easy-and-the-hard-things-possible) and this may require us to change the API at times.
- React Navigation does not directly use most of the native navigation APIs on iOS and Android; rather, it uses the lowest level pieces and then re-creates some subset of the APIs on top. This is a conscious choice in order to make it possible for users to customize any part of the navigation experience (because it's implemented in JavaScript) and to be able to debug issues that they encounter without needing to learn Objective C / Swift / Java / Kotlin.
  - If you need the exact platform behavior you are better off using another library that wraps the platform APIs. Read more about these in [Alternatives](alternatives.md) and be sure to understand the tradeoffs that they make before digging in!
- Because much of the logic for React Navigation runs in JavaScript rather than in native, the usual concerns about blocking the JavaScript thread come into play.
- If you need to support master-detail split-views on iPad, you may want to use another library. This has not yet been implemented in React Navigation, although you can build it yourself if you like.

---

## Alternative libraries

Source: https://reactnavigation.org/docs/4.x/alternatives

React Navigation isn't your only option for routing and navigation in React Native. If the [pitch & anti-pitch](pitch.md) or the API design leave you wanting to explore other options, here are a few to consider.

- [react-native-router-flux](https://github.com/aksonov/react-native-router-flux): this library is based on React Navigation but provides you with a different API to interact with it.
- [react-native-navigation](https://github.com/wix/react-native-navigation): uses the underlying native APIs on iOS and Android, this is a popular alternative to React Navigation and worth considering if you value adhering to the platform conventions exactly and do not care as much about customization.

---

## React Navigation contributor guide

Source: https://reactnavigation.org/docs/4.x/contributing

Want to help improve React Navigation? Your help would be greatly appreciated!

Here are some of the ways to contribute to the project:

- [Reporting Bugs](#reporting-bugs)
- [Improving the Documentation](#improving-the-documentation)
- [Responding to Issues](#responding-to-issues)
- [Bug Fixes](#bug-fixes)
- [Suggesting a Feature](#suggesting-a-feature)
- [Big Pull Requests](#big-pull-requests)

And here are a few helpful resources to aid in getting started:

- [Issue Template](#issue-template)
- [Pull Request Template](#pull-request-template)
- [Forking the Repository](#forking-the-repository)
- [Code Review Guidelines](#code-review-guidelines)
- [Run the Example App](#run-the-example-app)
- [Run the Website](#run-the-website)
- [Run Tests](#run-tests)

## Contributing

### Reporting Bugs

You can't write code without writing the occasional bug. Especially as React Navigation is moving quickly, bugs happen. When you think you've found one here's what to do:

1. Search the existing issues for one like what you're seeing. If you see one, add a 👍 reaction (please no +1 comments). Read through the comments and see if you can provide any more valuable information to the thread
2. If there are no other issues like yours then create a new one. Be sure to follow the [issue template](https://github.com/react-navigation/react-navigation/blob/v4.1.1/.github/ISSUE_TEMPLATE/bug_report.md).

Creating a high quality reproduction is critical. Without it we likely can't fix the bug and, in an ideal situation, you'll find out that it's not actually a bug of the library but simply done incorrectly in your project. Instant bug fix!

### Improving the Documentation

Any successful projects needs quality documentation and React Navigation is no different.

Read more about the documentation on the [react-navigation/react-navigation.github.io repository](https://github.com/react-navigation/react-navigation.github.io).

### Responding to Issues

Another great way to contribute to React Navigation is by responding to issues. Maybe it's answering someone's question, pointing out a small typo in their code, or helping them put together a reproduction. If you're interested in a more active role in React Navigation start with responding to issues - not only is it helpful but it demonstrates your commitment and knowledge of the code!

### Bug Fixes

Find a bug, fix it up, all day long you'll have good luck! Like it was mentioned earlier, bugs happen. If you find a bug do the following:

1. Check if a pull request already exists addressing that bug. If it does give it a review and leave your comments
2. If there isn't already a pull request then figure out the fix! If it's relatively small go ahead and fix it and submit a pull request. If it's a decent number of changes file an issue first so we can discuss it (see the [Big Pull Requests](#big-pull-requests) section)
3. If there is an issue related to that bug leave a comment on it, linking to your pull request, so others know it's been addressed.

Check out the [help wanted](https://github.com/react-navigation/react-navigation/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) and [good first issue](https://github.com/react-navigation/react-navigation/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) tags to see where you can start helping out!

### Suggesting a Feature

Is there something you want to see from React Navigation? Please [create a feature request on Canny](https://react-navigation.canny.io/feature-requests).

### Big Pull Requests

For any changes that will add/remove/modify multiple files in the project (new features or bug fixes) hold off on writing code right away. There's a few reasons for that

1. Big pull requests take a lot of time to review and it's sometimes hard to pick up the context
2. Often you may not have to make as big of a change as you expect

With that in mind, here's the suggestion

1. Open an issue and clearly define what it is you want to accomplish and how you intend to accomplish it
2. Discuss that solution with the community and maintainers. Provide context, establish edge cases, and figure out the design
3. Decide on a plan of action
4. Write the code and submit the PR
5. Review the PR. This can take some time but, if you followed the steps above, hopefully it won't take too much time.

The reason we want to do this is to save everyone time. Maybe that feature already exists but isn't documented? Or maybe it doesn't fit with the library. Regardless, by discussing a major change up front you're saving your time and others time as well.

### Interface Changes & Types

If you ever find yourself making a change to the project's public interface (the API) then you should make sure to update the corresponding library definitions for Flow. These "libdefs" specify our API's types so that library users can typecheck their code. An example of a qualifying change would be adding a new navigation option.

The libdef (located at `flow/react-navigation.js`) will need to be updated such that running `flow` in the `example` folder produces no errors.

1. Follow the instructions in the [Run the Example App](#run-the-example-app) section to prepare the `NavigationPlayground` example and install `flow` into the example's local `node_modules/.bin` folder.
2. Run `flow` to see any current errors.
3. If no errors occur as a result of an API change, that indicates that we don't have any coverage in the `NavigationPlayground` example project for your API change. This is frequently the case - for instance, if you add a new navigation option. In this case, you must add an example use of your new feature to `NavigationPlayground` so that you can test your libdef changes, and so that we can keep your feature properly tested and typed in perpetuity.
4. Once you are seeing errors, go ahead and update the libdef (located at `flow/react-navigation.js`) so that there are no longer any errors when you run `flow` from within `example`.
5. Include the libdef changes in the PR for your new feature. Make sure to flag to the maintainers that your PR has a libdef change, so that when the next version of the library is released, we make sure to upload the updated libdef to the `flow-typed` repo.

## Information

### Issue Template

Before submitting an issue, please take a look at the [issue template](https://github.com/react-navigation/react-navigation/blob/v4.1.1/.github/ISSUE_TEMPLATE/bug_report.md) and follow it. This is in place to help everyone better understand the issue you're having and reduce the back and forth to get the necessary information.

Yes, it takes time and effort to complete the issue template. But that's the only way to ask high quality questions that actually get responses.

Would you rather take 1 minute to create an incomplete issue report and wait months to get any sort of response? Or would you rather take 20 minutes to fill out a high quality issue report, with all the necessary elements, and get a response in days? It's also a respectful thing to do for anyone willing to take the time to review your issue.

### Pull Request Template

Much like the issue template, the [pull request template](https://github.com/react-navigation/react-navigation/blob/v4.1.1/.github/PULL_REQUEST_TEMPLATE.md) lays out instructions to ensure your pull request gets reviewed in a timely manner and reduces the back and forth. Make sure to look it over before you start writing any code.

### Forking the Repository

- Fork [`react-navigation`](https://github.com/react-navigation/react-navigation) on GitHub
- Run these commands in the terminal to download locally and install it:

```bash
git clone https://github.com/<USERNAME>/react-navigation.git
cd react-navigation
git remote add upstream https://github.com/react-navigation/react-navigation.git
yarn install
```

### Code Review Guidelines

Look around. Match the style of the rest of the codebase. This project uses ESLint to ensure consistency throughout the project. You can check your project by running

```bash
yarn lint
```

If any errors occur you'll either have to manually fix them or you can attempt to automatically fix them by running `yarn lint --fix`.

### Run the Example App

The [NavigationPlayground](https://github.com/react-navigation/react-navigation/tree/4.x/example) example app includes a variety of patterns and is used as a simple way for contributors to manually integration test changes. See the [README](https://github.com/react-navigation/react-navigation/blob/4.x/example/README.md) for instructions to run it.

### Run the Website

For development mode and live-reloading:

```bash
cd website
yarn install
yarn start
```

To run the website in production mode with server rendering:

```bash
yarn prod
```

If you've made any changes to the `docs` directory you'll need to run `yarn build-docs` from the root of the project before they're picked up by the website.

### Run Tests

React Navigation has tests implemented in [Jest](https://facebook.github.io/jest/). To run either of these, from the React Navigation directory, run either of the following commands (after installing the `node_modules`) to run tests or type-checking.

```bash
yarn test
```

These commands will be run by our CI and are required to pass before any contributions are merged.

---