HomeGuidesReferenceLearn

Reference version

ArchiveExpo SnackDiscord and ForumsNewsletter

Expo Router

GitHub

npm

A file-based routing library for React Native and web applications.

Android
iOS
Web

expo-router is a routing library for React Native and web apps. It enables navigation management using a file-based routing system and provides native navigation components and is built on top of React Navigation.

Installation

Terminal
- npx expo install expo-router

Configuration in app config

If you are using the default template to create a new project, expo-router config plugin is automatically configured in the app config automatically.

Example app.json with config plugin

app.json
{
  "expo": {
    "plugins": ["expo-router"]
  }
}

Usage

Find more information and guides about using expo-router in Expo Router section.

API

import { Stack, Tabs, Link } from 'expo-router';

Components

ErrorBoundary

Type: React.Element<ErrorBoundaryProps>

ErrorBoundaryProps

Props passed to a page's ErrorBoundary export.

Android
iOS
Web

error

Type: Error

The error that was thrown.

Android
iOS
Web

retry

Type: () => Promise<void>

A function that will re-render the route component by clearing the error state.

Link

Type: React.Element<PropsWithChildren<LinkProps<T>>>

Component that renders a link using href to another route. By default, it accepts children and wraps them in a <Text> component.

Uses an anchor tag (<a>) on web and performs a client-side navigation to preserve the state of the website and navigate faster. The web-only attributes such as target, rel, and download are supported and passed to the anchor tag on web. See WebAnchorProps for more details.

Note: Client-side navigation works with both single-page apps, and static-rendering.

Example

import { Link } from 'expo-router';
import { View } from 'react-native';

export default function Route() {
 return (
  <View>
   <Link href="/about">About</Link>
  </View>
 );
}
Android
iOS
Web

asChild

Optional • Type: boolean

Used to customize the Link component. It will forward all props to the first child of the Link. Note that the child component must accept onPress or onClick props. The href and role are also passed to the child.

Example

import { Link } from 'expo-router';
import { Pressable, Text } from 'react-native';

export default function Route() {
 return (
  <View>
   <Link href="/home" asChild>
     <Pressable>
      <Text>Home</Text>
     </Pressable>
   </Link>
  </View>
 );
}
Android
iOS
Web

className

Optional • Type: string

On native, this can be used with CSS interop tools like Nativewind. On web, this sets the HTML class directly.

Android
iOS
Web

href

Type: Href<T>

The path of the route to navigate to. It can either be:

  • string: A full path like /profile/settings or a relative path like ../settings.
  • object: An object with a pathname and optional params. The pathname can be a full path like /profile/settings or a relative path like ../settings. The params can be an object of key-value pairs.

Example

Dynamic
import { Link } from 'expo-router';
import { View } from 'react-native';

export default function Route() {
 return (
  <View>
   <Link href="/about">About</Link>
   <Link
    href={{
      pathname: '/user/[id]',
      params: { id: 'bacon' }
    }}>
      View user
   </Link>
  </View>
 );
}
Android
iOS
Web

onPress

Optional • Type: (e: MouseEvent<HTMLAnchorElement, MouseEvent> | GestureResponderEvent) => void

This function is called on press. Text intrinsically supports press handling with a default highlight state (which can be disabled with suppressHighlighting).

Android
iOS
Web

push

Optional • Type: boolean

Always pushes a new route, and never pops or replaces to existing route. You can push the current route multiple times or with new parameters.

Example

import { Link } from 'expo-router';
import { View } from 'react-native';

export default function Route() {
 return (
  <View>
    <Link push href="/feed">Login</Link>
  </View>
 );
}
Android
iOS
Web

relativeToDirectory

Optional • Type: boolean

Relative URL references are either relative to the directory or the document. By default, relative paths are relative to the document.

See: Resolving relative references in Mozilla's documentation.

Android
iOS
Web

replace

Optional • Type: boolean

Removes the current route from the history and replace it with the specified URL. This is useful for redirects.

Example

import { Link } from 'expo-router';
import { View } from 'react-native';

export default function Route() {
 return (
  <View>
    <Link replace href="/feed">Login</Link>
  </View>
 );
}
Android
iOS
Web

withAnchor

Optional • Type: boolean

Replaces the initial screen with the current route.

Inherited Props

Slot

Type: React.Element<Omit<NavigatorProps<any>, 'children'>>

Renders the currently selected content.

There are actually two different implementations of <Slot/>:

  • Used inside a _layout as the Navigator
  • Used inside a Navigator as the content

Since a custom Navigator will set the NavigatorContext.contextKey to the current _layout, you can use this to determine if you are inside a custom navigator or not.

Hooks

Android
iOS
Web

useFocusEffect(effect, do_not_pass_a_second_prop)

ParameterTypeDescription
effectEffectCallback

Memoized callback containing the effect, should optionally return a cleanup function.

do_not_pass_a_second_prop
(optional)		undefined-

Hook to run an effect whenever a route is focused. Similar to React.useEffect.

This can be used to perform side-effects such as fetching data or subscribing to events. The passed callback should be wrapped in React.useCallback to avoid running the effect too often.

Returns:

void

Example

import { useFocusEffect } from 'expo-router';
import { useCallback } from 'react';

export default function Route() {
  useFocusEffect(
    // Callback should be wrapped in `React.useCallback` to avoid running the effect too often.
    useCallback(() => {
      // Invoked whenever the route is focused.
      console.log('Hello, I'm focused!');

      // Return function is invoked whenever the route gets out of focus.
      return () => {
        console.log('This route is now unfocused.');
      };
    }, []);
   );

 return </>;
}
Android
iOS
Web

useGlobalSearchParams()

Returns URL parameters for globally selected route, including dynamic path segments. This function updates even when the route is not focused. Useful for analytics or other background operations that don't draw to the screen.

Route URL example: acme://profile/baconbrix?extra=info.

When querying search params in a stack, opt-towards using useLocalSearchParams because it will only update when the route is focused.

Note: For usage information, see Local versus global search parameters.

Returns:

RouteParams<TRoute, TParams>

Example

app/profile/[user].tsx
import { Text } from 'react-native';
import { useGlobalSearchParams } from 'expo-router';

export default function Route() {
  // user=baconbrix & extra=info
  const { user, extra } = useGlobalSearchParams();

  return <Text>User: {user}</Text>;
}
Android
iOS
Web

useLocalSearchParams()

Returns the URL parameters for the contextually focused route. Useful for stacks where you may push a new screen that changes the query parameters. For dynamic routes, both the route parameters and the search parameters are returned.

Route URL example: acme://profile/baconbrix?extra=info.

To observe updates even when the invoking route is not focused, use useGlobalSearchParams.

Note: For usage information, see Local versus global search parameters.

Returns:

RouteParams<TRoute, TParams>

Example

app/profile/[user].tsx
import { Text } from 'react-native';
import { useLocalSearchParams } from 'expo-router';

export default function Route() {
 // user=baconbrix & extra=info
 const { user, extra } = useLocalSearchParams();

 return <Text>User: {user}</Text>;
}
Android
iOS
Web

useNavigation(parent)

ParameterTypeDescription
parent
(optional)		string

Provide an absolute path such as /(root) to the parent route or a relative path like ../../ to the parent route.


Returns the underlying React Navigation navigation prop to imperatively access layout-specific functionality like navigation.openDrawer() in a Drawer layout.

Returns:

T

The navigation object for the current route.

See: React Navigation documentation on navigation dependent functions for more information.

Example

app/index.tsx
import { useNavigation } from 'expo-router';

export default function Route() {
  // Access the current navigation object for the current route.
  const navigation = useNavigation();

  return (
    <View>
      <Text onPress={() => {
        // Open the drawer view.
        navigation.openDrawer();
      }}>
        Open Drawer
      </Text>
    </View>
  );
}

When using nested layouts, you can access higher-order layouts by passing a secondary argument denoting the layout route. For example, /menu/_layout.tsx is nested inside /app/orders/, you can use useNavigation('/orders/menu/').

Example

app/orders/menu/index.tsx
import { useNavigation } from 'expo-router';

export default function MenuRoute() {
  const rootLayout = useNavigation('/');
  const ordersLayout = useNavigation('/orders');

  // Same as the default results of `useNavigation()` when invoked in this route.
  const parentLayout = useNavigation('/orders/menu');
}

If you attempt to access a layout that doesn't exist, an error such as Could not find parent navigation with route "/non-existent" is thrown.

Android
iOS
Web

useNavigationContainerRef()

Returns:

NavigationContainerRefWithCurrent<RootParamList>

The root <NavigationContainer /> ref for the app. The ref.current may be null if the <NavigationContainer /> hasn't mounted yet.

Android
iOS
Web

usePathname()

Returns the currently selected route location without search parameters. For example, /acme?foo=bar returns /acme. Segments will be normalized. For example, /[id]?id=normal becomes /normal.

Returns:

string

Example

app/profile/[user].tsx
import { Text } from 'react-native';
import { useSegments } from 'expo-router';

export default function Route() {
  // segments = ["profile", "[user]"]
  const segments = useSegments();

  return <Text>Hello</Text>;
}

Deprecated Use useNavigationContainerRef instead, which returns a React ref.

Android
iOS
Web

useRootNavigation()

Returns:

null | NavigationContainerRef<RootParamList>

Android
iOS
Web

useRootNavigationState()

Returns the navigation state of the navigator which contains the current screen.

Returns:

any

Example

import { useRootNavigationState } from 'expo-router';

export default function Route() {
 const { routes } = useRootNavigationState();

 return <Text>{routes[0].name}</Text>;
}
Android
iOS
Web

useRouter()

Returns the Router object for imperative navigation.

Returns:

Router

Example

import { useRouter } from 'expo-router';
import { Text } from 'react-native';

export default function Route() {
 const router = useRouter();

 return (
  <Text onPress={() => router.push('/home')}>Go Home</Text>
 );
}
Android
iOS
Web

useSegments()

Returns a list of selected file segments for the currently selected route. Segments are not normalized, so they will be the same as the file path. For example, /[id]?id=normal becomes ["[id]"].

Example

app/profile/[user].tsx
import { Text } from 'react-native';
import { useSegments } from 'expo-router';

export default function Route() {
  // segments = ["profile", "[user]"]
  const segments = useSegments();

  return <Text>Hello</Text>;
}

useSegments can be typed using an abstract. Consider the following file structure:

- app
  - [user]
    - index.tsx
    - followers.tsx
  - settings.tsx

This can be strictly typed using the following abstract with useSegments hook:

const [first, second] = useSegments<['settings'] | ['[user]'] | ['[user]', 'followers']>()

Methods

Android
iOS
Web

Redirect(namedParameters)

ParameterType
namedParameters{ href: Href }

Redirects to the href as soon as the component is mounted.

Returns:

null

Example

import { View, Text } from 'react-native';
import { Redirect } from 'expo-router';

export default function Page() {
 const { user } = useAuth();

 if (!user) {
   return <Redirect href="/login" />;
 }

 return (
   <View>
     <Text>Welcome Back!</Text>
   </View>
 );
}
Android
iOS
Web

withLayoutContext(Nav, processor)

ParameterType
NavT
processor
(optional)		(options: ScreenProps[]) => ScreenProps[]

Returns a navigator that automatically injects matched routes and renders nothing when there are no children. Return type with children prop optional.

Returns:

Component<PropsWithoutRef<PickPartial<ComponentProps<T>, 'children'>>> & { Screen: (props: ScreenProps<TOptions, TState, TEventMap>) => null }

Types

Android
iOS
Web

EffectCallback()

Memoized callback containing the effect, should optionally return a cleanup function.

Returns:

undefined | void | () => void

Android
iOS
Web

Href

Type: GeneratedHref<T>

The main routing type for Expo Router. It includes all available routes with strongly typed parameters. It can either be:

  • string: A full path like /profile/settings or a relative path like ../settings.
  • object: An object with a pathname and optional params. The pathname can be a full path like /profile/settings or a relative path like ../settings. The params can be an object of key-value pairs.

It can also accept an optional <T> parameter to correctly type dynamic routes string.

For example, without the generic the route /folder/[slug] will be typed as /folder/${string}, which is incorrect as /folder/apple/orange would be valid. However, by passing desired route as a generic Href<'/folder/apple'>, it will validate against this edge case.

Android
iOS
Web

NativeIntent

Created by using a special file called +native-intent.tsx at the top-level of your project's app directory. It exports redirectSystemPath or legacy_subscribe functions, both methods designed to handle URL/path processing.

Useful for re-writing URLs to correctly target a route when unique/referred URLs are incoming from third-party providers or stale URLs from previous versions.

See: For more information on how to use NativeIntent, see Customizing links.

NameTypeDescription
legacy_subscribe
(optional)		(listener: (url: string) => void) => undefined | void | () => void
Experimentally available in SDK 52.

Useful as an alternative API when a third-party provider doesn't support Expo Router but has support for React Navigation via Linking.subscribe() for existing projects.

Using this API is not recommended for newer projects or integrations since it is incompatible with Server Side Routing and Static Rendering, and can become challenging to manage while offline or in a low network environment.

redirectSystemPath
(optional)		(event: { initial: boolean, path: string }) => Promise<string> | string

A special method used to process URLs in native apps. When invoked, it receives an options object with the following properties:

  • path: represents the URL or path undergoing processing.
  • initial: a boolean indicating whether the path is the app's initial URL.

It's return value should either be a string or a Promise<string>. Note that throwing errors within this method may result in app crashes. It's recommended to wrap your code inside a try/catch block and utilize .catch() when appropriate.

See: For usage information, see Redirecting system paths.

Android
iOS
Web

PickPartial

Literal Type: multiple types

The list of input keys will become optional, everything else will remain the same.

Acceptable values are: Omit<T, K> | Partial<Pick<T, K>>

Android
iOS
Web

ResultState

Type: PartialState<NavigationState> extended by:


NameTypeDescription
state
(optional)		ResultState-
Android
iOS
Web

Router

Returns router object for imperative navigation API.

Example

import { router } from 'expo-router';
import { Text } from 'react-native';

export default function Route() {

 return (
  <Text onPress={() => router.push('/home')}>Go Home</Text>
 );
}
NameTypeDescription
back() => void

Goes back in the navigation history.

canDismiss() => boolean

Checks if it is possible to dismiss the current screen. Returns true if the router is within the stack with more than one screen in stack's history.

canGoBack() => boolean

Navigates to a route in the navigator's history if it supports invoking the back function.

dismiss(count: number) => void

Navigates to the a stack lower than the current screen using the provided count if possible, otherwise 1.

If the current screen is the only route, it will dismiss the entire stack.

dismissAll() => void

Returns to the first screen in the closest stack. This is similar to popToTop stack action.

navigate(href: Href<T>, options: NavigationOptions) => void

Navigates to the provided href.

push(href: Href<T>, options: NavigationOptions) => void

Navigates to the provided href using a push operation if possible.

replace(href: Href<T>, options: NavigationOptions) => void

Navigates to route without appending to the history. Can be used with useFocusEffect to redirect imperatively to a new screen.

See: Using useRouter() hook to redirect.

setParams(params: Partial<RouteParamInput<T>>) => void

Updates the current route's query params.

Android
iOS
Web

ScreenProps

NameTypeDescription
getId
(optional)		({ params }: { params: Record<string, any> }) => string | undefined-
initialParams
(optional)		Record<string, any>-
listeners
(optional)		ScreenListeners<TState, TEventMap> | (prop: { navigation: any, route: RouteProp<ParamListBase, string> }) => ScreenListeners<TState, TEventMap>-
name
(optional)		string

Name is required when used inside a Layout component.

options
(optional)		TOptions | (prop: { navigation: any, route: RouteProp<ParamListBase, string> }) => TOptions-
redirect
(optional)		boolean

Redirect to the nearest sibling route. If all children are redirect={true}, the layout will render null as there are no children to render.

Web

WebAnchorProps

NameTypeDescription
download
(optional)		string

Specifies that the href should be downloaded when the user clicks on the link, instead of navigating to it. It is typically used for links that point to files that the user should download, such as PDFs, images, documents, and more.

The value of the download property, which represents the filename for the downloaded file. This property is passed to the underlying anchor (<a>) tag.

Example
<Link href="/image.jpg" download="my-image.jpg">Download image</Link>
rel
(optional)		string

Specifies the relationship between the href and the current route.

Common values:

  • nofollow: Indicates to search engines that they should not follow the href. This is often used for user-generated content or links that should not influence search engine rankings.
  • noopener: Suggests that the href should not have access to the opening window's window.opener object, which is a security measure to prevent potentially harmful behavior in cases of links that open new tabs or windows.
  • noreferrer: Requests that the browser does not send the Referer HTTP header when navigating to the href. This can enhance user privacy.

The rel property is primarily used for informational and instructive purposes, helping browsers and web crawlers make better decisions about how to handle and interpret the links on a web page. It is important to use appropriate rel values to ensure that links behave as intended and adhere to best practices for web development and SEO (Search Engine Optimization).

This property is passed to the underlying anchor (<a>) tag.

Example
<Link href="https://expo.dev" rel="nofollow">Go to Expo</Link>`
target
(optional)		'_self' | '_blank' | '_parent' | '_top' | string & object

Specifies where to open the href.

  • _self: the current tab.
  • _blank: opens in a new tab or window.
  • _parent: opens in the parent browsing context. If no parent, defaults to _self.
  • _top: opens in the highest browsing context ancestor. If no ancestors, defaults to _self.

This property is passed to the underlying anchor (<a>) tag.

Default:'_self'
Example
<Link href="https://expo.dev" target="_blank">Go to Expo in new tab</Link>