Skip to main content

Navigation Container

The global React Navigation <NavigationContainer /> is completely managed by Expo Router. Expo Router provides systems for achieving the same functionality as the NavigationContainer without needing to use it directly.

ref​

The NavigationContainer ref should not be accessed directly. Use the following methods instead.

Methods on the ref​

resetRoot​​

Navigate to the initial route of the application. For example, if your app starts at / (recommended), then you can replace the current route with / using this method.

import { useRouter } from "expo-router";

function Example() {
  const router = useRouter();

  return (
    <Text
      onPress={() => {
        // Go to the initial route of the application.
        router.replace("/");
      }}
    >
      Reset App
    </Text>
  );
}

getRootState​

Use useRootNavigationState().

getCurrentRoute​

Unlike React Navigation, Expo Router can reliably represent any route with a string. Use the usePathname() or useSegments() hooks to identify the current route.

getCurrentOptions​

Use the useLocalSearchParams() hook to get the current route's query parameters.

addListener​

The following events can be migrated:

state​

Use the usePathname() or useSegments() hooks to identify the current route. Use in conjunction with useEffect(() => {}, [...]) to observe changes.

options​

Use the useLocalSearchParams() hook to get the current route's query parameters. Use in conjunction with useEffect(() => {}, [...]) to observe changes.

props​

Migrate the following <NavigationContainer /> props:

initialState​

In Expo Router, you can rehydrate your application state from a route string (e.g. /user/evanbacon). Use redirects to handle initial states. See shared routes for advanced redirects.

Avoid using this pattern in favor of deep linking (e.g. user opens your app to /profile rather than from the home screen) as it is most analogous to the web. If an app crashes due to a particular screen, it's best to avoid automatically navigating back to that exact screen when the app starts as it may require reinstalling the app to fix.

onStateChange​

Use the usePathname(), useSegments(), and useGlobalSearchParams() hooks to identify the current route state. Use in conjunction with useEffect(() => {}, [...]) to observe changes.

onReady​

In React Navigation, onReady is most often used to determine when the splash screen should hide or when to track screens using analytics. Expo Router has special handling for both these use cases. Assume the navigation is always ready in for navigation events in Expo Router.

onUnhandledAction​

Actions are always handled in Expo Router. Use dynamic routes and 404 screens in favor of onUnhandledAction.

linking​

The linking prop is automatically constructed based on the files to the app/ directory.

fallback​

The fallback prop is automatically handled by Expo Router. Learn more in the Splash Screen guide.

theme​

Use the <ThemeProvider /> component instead. Learn more in the Themes guide.

children​

The children prop is a automatically populated based on the files in the app/ directory, and the currently open URL.

independent​

Expo Router does not support independent containers. This is because the router is responsible for managing the single <NavigationContainer />. Any additional containers will not be automatically managed by Expo Router.

documentTitle​

This property is not yet supported in Expo Router. Set the web page title using screen options.

ref​

Use the useRootNavigation() hook instead.