Expo Docs MCP Server

--- title: Migrate from React Navigation sidebar_title: React Navigation description: Learn how to migrate a project using React Navigation to Expo Router. --- Both React Navigation and Expo Router are Expo frameworks for routing and navigation. Expo Router is a wrapper around React Navigation and many of the concepts are the same. ## Pitch Along with all the benefits of React Navigation, Expo Router enables automatic deep linking, [type safety](/router/reference/typed-routes), [deferred bundling](/router/reference/async-routes), [static rendering on web](/router/reference/static-rendering), and more. ## Anti-pitch If your app uses a custom `getPathFromState` or `getStateFromPath` component, it may not be a good fit for Expo Router. If you're using these functions to support [shared routes](/router/advanced/shared-routes) then you should be fine as Expo Router has built-in support for this. ## Recommendations We recommend making the following modifications to your codebase before beginning the migration: - Split React Navigation screen components into individual files. For example, if you have ``, then ensure the `HomeScreen` component is in its own file. - Convert the project to [TypeScript](/guides/typescript/#migrating-existing-javascript-project). This will make it easier to spot errors that may occur during the migration. - Convert relative imports to [typed aliases](/guides/typescript/#path-aliases-optional). For example, `../../components/button.tsx` to `@/components/button` before starting the migration. This makes it easier to move screens around the filesystem without having to update the relative paths. - Migrate away from `resetRoot`. This is used to "restart" the app while running. This is generally considered bad practice, and you should restructure your app's navigation so this never needs to happen. - Rename the initial route to `index`. Expo Router considers the route that is opened on launch to match `/`, React Navigation users will generally use something such as "Home" for the initial route. ### Refactor search parameters Refactor screens to [use serializable top-level query parameters](https://reactnavigation.org/docs/params/#what-should-be-in-params). We recommend this in React Navigation as well. In Expo Router, search parameters can only serialize top-level values such as `number`, `boolean`, and `string`. React Navigation doesn't have the same restrictions, so users can sometimes pass invalid parameters like Functions, Objects, Maps, and so on. If your code has something similar to the below: ```js const navigation = useNavigation(); navigation.push('Followers', { onPress: profile => { navigation.push('User', { profile }); }, }); ``` Consider restructuring so the function can be accessed from the "followers" screen. In this case, you can access the router and push directly from the "followers" screen. ### Eagerly load UI It's common in React Native apps to `return null` from the root component while assets and fonts are loading. This is bad practice and generally unsupported in Expo Router. If you absolutely must defer rendering, then ensure you don't attempt to navigate to any screens. Historically this pattern exists because React Native will throw errors if you use custom fonts that haven't loaded yet. We changed this upstream in React Native 0.72 (SDK 49) so the default behavior is to swap the default font when the custom font loads. If you'd like to hide individual text elements until a font has finished loading, write a wrapper ``, which returns null until the font has loaded. On web, returning `null` from the root will cause [static rendering](/router/reference/static-rendering) to skip all of the children, resulting in no searchable content. This can be tested by using "View Page Source" in Chrome, or by disabling JavaScript and reloading the page. ## Migration ### Delete unused or managed code Expo Router automatically adds `react-native-safe-area-context` support. ```diff - import { SafeAreaProvider } from 'react-native-safe-area-context'; return ( - <SafeAreaProvider> - </SafeAreaProvider> ) } ``` Expo Router **does not** add `react-native-gesture-handler` (as of v3), so you'll have to add this yourself if you are using Gesture Handler or `` layout. Avoid using this package on web since it adds a lot of JavaScript that is often unused. ### Copy screens to the app directory Create an **app** directory at the root of your repo, or in a root **src** directory. Layout the structure of your app by creating files according to the [application of Expo Router rules](/router/basics/core-concepts/#the-rules-of-expo-router-applied). Kebab-case and lowercase letters are considered best practice for route filenames. Replace navigators with directories, for example: {/* prettier-ignore */} ```jsx React Navigation function HomeTabs() { return ( <Tab.Navigator> </Tab.Navigator> ); } function App() { return ( // NavigationContainer is managed by Expo Router. <NavigationContainer linking={ /* @info Delete the linking configuration, this is managed by Expo Router. */ { // ...linking configuration } /* @end */ } > <Stack.Navigator> /* @info Standard screens can be moved to files. */ /* @end */ /* @info A screen that exports a navigator should be converted to a directory with a layout route. */ /* @end */ </Stack.Navigator> </NavigationContainer> ); } ``` **Expo Router:** - Rename the "main" route from **Home** to **index** to ensure it matches the `/` path. - Convert names to lowercase. - Move all the screens to the appropriate file locations inside the app directory. This may take some experimenting. ```jsx app/_layout.js return ( <Stack> </Stack> ); } ``` The tab navigator will be moved to a subdirectory. ```jsx app/(home)/_layout.js return ; } ``` ### Use Expo Router hooks React Navigation v6 and lower will pass the props `{ navigation, route }` to every screen. This pattern is going away in React Navigation, and we never introduced it to the Expo Router. Instead, migrate `navigation` to the `useRouter` hook. ```diff + import { useRouter } from 'expo-router'; - navigation }) { - navigation.push('User', { user: 'bacon' }); + const router = useRouter(); + router.push('/users/bacon'); } ``` Similarly, migrate from the `route` prop to the [`useLocalSearchParams`](/router/reference/hooks/#uselocalsearchparams) hook. ```diff + import { useLocalSearchParams } from 'expo-router'; - route }) { - const user = route?.params?.user; + const { user } = useLocalSearchParams(); } ``` To access the [`navigation.navigate`](https://reactnavigation.org/docs/navigation-object/#navigate), import the `navigation` prop from [`useNavigation`](/router/reference/hooks/#usenavigation) hook. ```diff + import { useNavigation } from 'expo-router'; + const navigation = useNavigation(); return ( <Button onPress={navigation.navigate('screenName')}> ) }) ``` ### Migrate the Link component React Navigation and Expo Router both provide Link components. However, Expo's Link component uses `href` instead of [`to`](https://reactnavigation.org/docs/use-link-props/#to). ```jsx // React Navigation // Expo Router ``` React Navigation users will often create a custom Link component with the `useLinkProps` hook to control the child component. This isn't necessary in Expo Router, instead, use the `asChild` prop. ### Share screens across navigators It's common for React Navigation apps to reuse a set of routes across multiple navigators. This is generally used with tabs to ensure each tab can push any screen. In Expo Router, you can either migrate to [shared routes](/router/advanced/shared-routes) or create multiple files and re-export the same component from them. When you use groups or shared routes, you can navigate to specific tabs by using the fully qualified route name, for example, `/(home)/settings` instead of `/settings`. ### Migrate screen tracking events You may have your screen tracking setup according to our [React Navigation screen tracking guide](https://reactnavigation.org/docs/screen-tracking/), update it according to the [Expo Router screen tracking guide](/router/reference/screen-tracking). ### Use platform-specific components for screens Refer to the [platform-specific modules](/router/advanced/platform-specific-modules) guide for info on switching UI based on the platform. ### Replace the `NavigationContainer` The global React Navigation [``](https://reactnavigation.org/docs/navigation-container/) is completely managed in Expo Router. Expo Router provides systems for achieving the same functionality as the `NavigationContainer` without needing to use it directly. <Collapsible summary="API substitutions"> ### Ref The `NavigationContainer` ref should not be accessed directly. Use the following methods instead. #### `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. ```jsx function Example() { const router = useRouter(); return ( <Text onPress={() => { // Go to the initial route of the application. router.replace('/'); }}> Reset App ); } ``` #### `getRootState` Use `useRootNavigationState()`. #### `getCurrentRoute` Unlike React Navigation, Expo Router can reliably represent any route with a string. Use the [`usePathname()`](/router/reference/hooks/#usepathname) or [`useSegments()`](/router/reference/hooks/#usesegments) hooks to identify the current route. #### `getCurrentOptions` Use the [`useLocalSearchParams()`](/router/reference/hooks/#uselocalsearchparams) hook to get the current route's query parameters. #### `addListener` The following events can be migrated: #### `state` Use the [`usePathname()`](/router/reference/hooks/#usepathname) or [`useSegments()`](/router/reference/hooks/#usesegments) hooks to identify the current route. Use in conjunction with `useEffect(() => {}, [...])` to observe changes. #### `options` Use the [`useLocalSearchParams()`](/router/reference/hooks/#uselocalsearchparams) hook to get the current route's query parameters. Use in conjunction with `useEffect(() => {}, [...])` to observe changes. ### props Migrate the following `` props: #### `initialState` In Expo Router, you can rehydrate your application state from a route string (for example, `/user/evanbacon`). Use [redirects](/router/reference/redirects/) to handle initial states. See [shared routes](/router/advanced/shared-routes/) for advanced redirects. Avoid using this pattern in favor of deep linking (for example, a 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()`](/router/reference/hooks/#usepathname), [`useSegments()`](/router/reference/hooks/#usesegments), and [`useGlobalSearchParams()`](/router/reference/hooks/#useglobalsearchparams) hooks to identify the current route state. Use in conjunction with `useEffect(() => {}, [...])` to observe changes. - If you're attempting to track screen changes, follow the [Screen Tracking guide](/router/reference/screen-tracking/). - React Navigation recommends avoiding [`onStateChange`](https://reactnavigation.org/docs/navigation-container/#onstatechange). #### `onReady` In React Navigation, [`onReady`](https://reactnavigation.org/docs/navigation-container/#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 of these use cases. Assume the navigation is always ready for navigation events in the Expo Router. - See the [Screen Tracking guide](/router/reference/screen-tracking/) for info on migrating analytics from React Navigation. - See the [Splash Screen feature](/develop/user-interface/splash-screen-and-app-icon/) for info on handling the splash screen. #### `onUnhandledAction` Actions are always handled in Expo Router. Use [dynamic routes](/router/basics/notation/#square-brackets) and [404 screens](/router/error-handling/#unmatched-routes) in favor of [`onUnhandledAction`](https://reactnavigation.org/docs/navigation-container/#onunhandledaction). #### `linking` The [`linking`](https://reactnavigation.org/docs/navigation-container/#linking) prop is automatically constructed based on the files to the **app** directory. #### `fallback` The [`fallback`](https://reactnavigation.org/docs/navigation-container/#fallback) prop is automatically handled by Expo Router. Learn more in the [Splash Screen](/versions/latest/sdk/splash-screen/) reference. #### `theme` In React Navigation, you set the theme for the entire app using the [``](https://reactnavigation.org/docs/navigation-container/#theme) component. Expo Router manages the root container for you, so instead you should set the theme using the `ThemeProvider` directly. ```tsx app/_layout.tsx return ( /* @info All layouts inside this provider will use the dark theme. */ /* @end */ ); } ``` You can use this technique at any layer of the app to set the theme for a specific layout. The current theme can be accessed with the `useTheme` hook from `@react-navigation/native`. #### `children` The `children` prop is automatically populated based on the files in the **app** directory and the currently open URL. #### `independent` Expo Router does not support [`independent`](https://reactnavigation.org/docs/navigation-container/#independent) containers. This is because the router is responsible for managing the single ``. Any additional containers will not be automatically managed by Expo Router. #### `documentTitle` Use the [Head component](/router/reference/static-rendering#meta-tags) to set the webpage title. #### `ref` Use the `useNavigationContainerRef()` hook instead. </Collapsible> ### Rewrite custom navigators If your project has a custom navigator, you can rewrite this or port it to Expo Router. To port, simply use the `withLayoutContext` function: ```js ``` To rewrite, use the `Navigator` component, which wraps the [`useNavigationBuilder`](https://reactnavigation.org/docs/custom-navigators#usenavigationbuilder) hook from React Navigation. The return value of `useNavigationBuilder` can be accessed with the `Navigator.useContext()` hook from inside the `` component. Properties can be passed to `useNavigationBuilder` using the props of the `` component, this includes `initialRouteName`, `screenOptions`, `router`. All of the `children` of a `` component will be rendered as-is. - `Navigator.useContext`: Access the React Navigation `state`, `navigation`, `descriptors`, and `router` for the custom navigator. - `Navigator.Slot`: A React component used to render the currently selected route. This component can only be rendered inside a `` component. #### Example Custom layouts have an internal context that is ignored when using the `` component without a `` component wrapping it. {/* prettier-ignore */} ```jsx return ( /* @info *//* @end */ ); } function Header() {; const pathname = usePathname(); return ( <Link href="/">Home</Link> <Link href="/profile" style={/* @info Use <code>pathname</code> to determine if the link is active. */[pathname === '/profile' && { color: 'blue' }]/* @end */}> Profile </Link> <Link href="/settings">Settings</Link> ); } ``` ### Use Expo Router's Splash Screen wrapper Expo Router wraps `expo-splash-screen` and adds special handling to ensure it's hidden after the navigation mounts, and whenever an unexpected error is caught. Simply migrate from importing `expo-splash-screen` to importing `SplashScreen` from `expo-router`. ### Navigation state observation If you're observing the navigation state directly, migrate to the [`usePathname`](/router/reference/hooks/#usepathname), [`useSegments`](/router/reference/hooks/#usesegments), and [`useGlobalSearchParams`](/router/reference/hooks/#useglobalsearchparams) hooks. ### Pass params to nested screens Instead of using the [nested screen navigation events](https://reactnavigation.org/docs/params/#passing-params-to-nested-navigators), use a qualified href: ```js // React Navigation navigation.navigate('Account', { screen: 'Settings', params: { user: 'jane' }, }); // Expo Router router.push({ pathname: '/account/settings', params: { user: 'jane' } }); ``` ### Set initial routes for deep linking and server navigation In React Navigation, you can use the `initialRouteName` property of the linking configuration. In Expo Router, use [layout settings](/router/advanced/router-settings). ### Reset navigation state You can use the [`reset`](https://reactnavigation.org/docs/navigation-actions/#reset) action from the React Navigation library to reset the navigation state. It is dispatched using the [`useNavigation`](/router/reference/hooks/#usenavigation) hook from Expo Router to access the `navigation` prop. In the below example, the `navigation` prop is accessible from the `useNavigation` hook and the `CommonActions.reset` action from `@react-navigation/native`. The object specified in the `reset` action replaces the existing navigation state with the new one. {/* prettier-ignore */} ```jsx app/screen.js const navigation = useNavigation(); const handleResetAction = () => { navigation.dispatch(CommonActions.reset({ routes: [{key: "(tabs)", name: "(tabs)"}] })) } return ( <> {/* ...rest of the code */} </> ); } ``` ### Migrate TypeScript types Expo Router can automatically generate [statically typed routes](/router/reference/typed-routes), this will ensure you can only navigate to valid routes. ## Additional information ### React Navigation themes React Navigation navigators `<Stack>`, `<Drawer>`, and `` use a shared appearance provider. In React Navigation, you set the theme for the entire app using the `` component. Expo Router manages the root container so that you can set the theme using the `ThemeProvider` directly. ```tsx app/_layout.tsx /* @info Import theme APIs from React Navigation directly. */ /* @end */ return ( /* @info All layouts inside this provider will use the dark theme. */ <ThemeProvider value={DarkTheme}> /* @end */ </ThemeProvider> ); } ``` You can use this technique at any layer of the app to set the theme for a specific layout. The current theme can be accessed via `useTheme` hook from `@react-navigation/native`. ### React Navigation Elements The [`@react-navigation/elements`](https://reactnavigation.org/docs/elements/) library provides a set of UI elements and helpers that can be used to build a navigation UI. These components are designed to be composable and customizable. You can reuse the default functionality from the library or build your navigator's UI on top of it. To use it with Expo Router, you need to install the library: <Tabs> <Tab label="npm"> </Tab> <Tab label="Yarn"> </Tab> To learn more about the components and utilities the library provides, see [Elements library](https://reactnavigation.org/docs/elements/) documentation.