React Navigation LogoReact Navigation
Version: 5.x

NavigationContainer

The NavigationContainer is responsible for managing your app state and linking your top-level navigator to the app environment.

The container takes care of platform specific integration and provides various useful functionality:

  1. Deep link integration with the linking prop.
  2. Notify state changes for screen tracking, state persistence etc.
  3. Handle system back button on Android by using the BackHandler API from React Native.

Usage:

import { NavigationContainer } from '@react-navigation/native';
import { createStackNavigator } from '@react-navigation/stack';


const Stack = createStackNavigator();


export default function App() {
  return (
    <NavigationContainer>
      <Stack.Navigator>{/* ... */}</Stack.Navigator>
    </NavigationContainer>
  );
}

Ref

It's also possible to attach a ref to the container to get access to various helper methods, for example, dispatch navigation actions.

Example:

function App() {
  const navigationRef = React.useRef(null);


  return (
    <View style={{ flex: 1 }}>
      <Button onPress={() => navigationRef.current?.navigate('Home')}>
        Go home
      </Button>
      <NavigationContainer ref={navigationRef}>{/* ... */}</NavigationContainer>
    </View>
  );
}

Keep in mind that the ref may be initially null in some situations (such as when deep linking is enabled). To make sure that the ref is initialized, you can use the onReady callback to get notified when the navigation container finishes mounting.

Methods on the ref

The ref object includes all of the common navigation methods such as navigate, goBack etc. See docs for CommonActions for more details.

Example:

navigationRef.current?.navigate(name, params);

All of these methods will act as if they were called inside the currently focused screen. It's important note that there must be a navigator rendered to handle these actions.

In addition to these methods, the ref object also includes the following special methods:

resetRoot

The resetRoot method lets you reset the state of the navigation tree to the specified state object:

navigationRef.current?.resetRoot({
  index: 0,
  routes: [{ name: 'Profile' }],
});

Unlike the reset method, this acts on the root navigator instead of navigator of the currently focused screen.

getRootState

The getRootState method returns the current navigation state containing the navigation states for all navigators in the navigation tree:

const state = navigationRef.current?.getRootState();

Note that the returned state object will be undefined if there are no navigators currently rendered.

getCurrentRoute

The getCurrentRoute method returns the route object for the currently focused screen in the whole navigation tree:

const route = navigationRef.current?.getCurrentRoute();

Note that the returned route object will be undefined if there are no navigators currently rendered.

getCurrentOptions

The getCurrentOptions method returns the options for the currently focused screen in the whole navigation tree:

const options = navigationRef.current?.getCurrentOptions();

Note that the returned options object will be undefined if there are no navigators currently rendered.

addListener

The addListener method lets you listen to the following events:

state

The event is triggered whenever the navigation state changes in any navigator in the navigation tree:

const unsubscribe = navigationRef.current?.addListener('state', (e) => {
  // You can get the raw navigation state (partial state object of the root navigator)
  console.log(e.data.state);


  // Or get the full state object with `getRootState()`
  console.log(navigationRef.current.getRootState());
});

This is analogous to the onStateChange method. The only difference is that the e.data.state object might contain partial state object unlike the state argument in onStateChange which will always contain the full state object.

options

The event is triggered whenever the options change for the currently focused screen in the navigation tree:

const unsubscribe = navigationRef.current?.addListener('options', (e) => {
  // You can get the new options for the currently focused screen
  console.log(e.data.options);
});

Props

initialState

Prop that accepts initial state for the navigator. This can be useful for cases such as deep linking, state persistence etc.

Example:

<NavigationContainer
  onStateChange={(state) => console.log('New state is', state)}
  initialState={initialState}
>
  {/* ... */}
</NavigationContainer>

Providing a custom initial state object will override the initial state object obtained via deep linking or from browser's URL. If you're providing an initial state object, make sure that you don't pass it on web and that there's no deep link by using Linking.getInitialURL():

const initialUrl = await Linking.getInitialURL();


if (Platform.OS !== 'web' && initialUrl == null) {
  // Only restore state if there's no deep link and we're not on web
}

See state persistence guide for more details on how to persist and restore state.

onStateChange

Note: Consider the navigator's state object to be internal and subject to change in a minor release. Avoid using properties from the navigation state object except index and routes, unless you really need it. If there is some functionality you cannot achieve without relying on the structure of the state object, please open an issue.

Function that gets called every time navigation state changes. It receives the new navigation state as the argument.

You can use it to track the focused screen, persist the navigation state etc.

onReady

Function which is called after the navigation container and all its children finish mounting for the first time. See docs regarding initialization of the ref for more details.

linking

Configuration for linking integration used for deep linking and URL support in browsers.

Example:

import { NavigationContainer } from '@react-navigation/native';


function App() {
  const linking = {
    prefixes: ['https://mychat.com', 'mychat://'],
    config: {
      screens: {
        Home: 'feed/:sort',
      },
    },
  };


  return (
    <NavigationContainer linking={linking} fallback={<Text>Loading...</Text>}>
      {/* content */}
    </NavigationContainer>
  );
}

See configuring links guide for more details on how to configure deep links and URL integration.

Options

linking.prefixes

URL prefixes to handle. You can provide multiple prefixes to support custom schemes as well as universal links.

Only URLs matching these prefixes will be handled. The prefix will be stripped from the URL before parsing.

Example:

<NavigationContainer
  linking={{
    prefixes: ['https://mychat.com', 'mychat://'],
    config: {
      screens: {
        Chat: 'feed/:sort',
      },
    },
  }}
>
  {/* content */}
</NavigationContainer>

This is only supported on iOS and Android.

linking.config

Config to fine-tune how to parse the path. The config object should represent the structure of the navigators in the app.

For example, if we have Catalog screen inside Home screen and want it to handle the item/:id pattern:

{
  screens: {
    Home: {
      screens: {
        Catalog: {
          path: 'item/:id',
          parse: {
            id: Number,
          },
        },
      },
    },
  }
}

The options for parsing can be an object or a string:

{
  screens: {
    Catalog: 'item/:id',
  }
}

When a string is specified, it's equivalent to providing the path option.

The path option is a pattern to match against the path. Any segments starting with : are recognized as a param with the same name. For example item/42 will be parsed to { name: 'item', params: { id: '42' } }.

The initialRouteName option ensures that the route name passed there will be present in the state for the navigator, e.g. for config:

{
  screens: {
    Home: {
      initialRouteName: 'Feed',
      screens: {
        Catalog: {
          path: 'item/:id',
          parse: {
            id: Number,
          },
        },
        Feed: 'feed',
      },
    },
  }
}

and URL : /item/42, the state will look like this:

{
  routes: [
    {
      name: 'Home',
      state: {
        index: 1,
        routes: [
          {
            name: 'Feed'
          },
          {
            name: 'Catalog',
            params: { id: 42 },
          },
        ],
      },
    },
  ],
}

The parse option controls how the params are parsed. Here, you can provide the name of the param to parse as a key, and a function which takes the string value for the param and returns a parsed value:

{
  screens: {
    Catalog: {
      path: 'item/:id',
      parse: {
        id: id => parseInt(id, 10),
      },
    },
  }
}

If no custom function is provided for parsing a param, it'll be parsed as a string.

linking.enabled

Optional boolean to enable or disable the linking integration. Defaults to true if the linking prop is specified.

linking.getStateFromPath

You can optionally override the way React Navigation parses deep links to a state object by providing your own implementation.

Example:

<NavigationContainer
  linking={{
    prefixes: ['https://mychat.com', 'mychat://'],
    config: {
      screens: {
        Chat: 'feed/:sort',
      },
    },
    getStateFromPath(path, config) {
      // Return a state object here
      // You can also reuse the default logic by importing `getStateFromPath` from `@react-navigation/native`
    },
  }}
>
  {/* content */}
</NavigationContainer>
linking.getPathFromState

You can optionally override the way React Navigation serializes state objects to link by providing your own implementation. This is necessary for proper web support if you have specified getStateFromPath.

Example:

<NavigationContainer
  linking={{
    prefixes: ['https://mychat.com', 'mychat://'],
    config: {
      screens: {
        Chat: 'feed/:sort',
      },
    },
    getPathFromState(state, config) {
      // Return a path string here
      // You can also reuse the default logic by importing `getPathFromState` from `@react-navigation/native`
    },
  }}
>
  {/* content */}
</NavigationContainer>

fallback

React Element to use as a fallback while we resolve the deep link. Defaults to null.

documentTitle

By default, React Navigation automatically updates the document title on Web to match the title option of the focused screen. You can disable it or customize it using this prop. It accepts a configuration object with the following options:

documentTitle.enabled

Whether document title handling should be enabled. Defaults to true.

documentTitle.formatter

Custom formatter to use if you want to customize the title text. Defaults to:

(options, route) => options?.title ?? route?.name;

Example:

import { NavigationContainer } from '@react-navigation/native';


function App() {
  return (
    <NavigationContainer
      documentTitle={{
        formatter: (options, route) =>
          `${options?.title ?? route?.name} - My Cool App`,
      }}
    >
      {/* content */}
    </NavigationContainer>
  );
}

theme

Custom theme to use for the navigation components such as the header, tab bar etc. See theming guide for more details and usage guide.

Edit this page