This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 55).
Expo Router
A file-based routing library for React Native and web applications.
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.
Learn about Expo Router basics, navigation patterns, core concepts, and more.
Installation
To use Expo Router in your project, you need to install. Follow the instructions from the Expo Router's installation guide:
Learn how to install Expo Router in your project.
Configuration in app config
If you are using the default template to create a new project, expo-router's config plugin is already configured in your app config.
Example app.json with config plugin
{ "expo": { "plugins": ["expo-router"] } }
Configurable properties
| Name | Default | Description |
|---|---|---|
root | "app" | Changes the routes directory from |
origin | undefined | Production origin URL where assets in the public folder are hosted. The fetch function is polyfilled to support relative requests from this origin in production. The development origin is inferred using the Expo CLI development server. |
headOrigin | undefined | A more specific origin URL used in the |
asyncRoutes | undefined | Enable async routes (lazy loading). Can be a boolean, a string ( |
platformRoutes | true | Enable or disable platform-specific routes (for example, index.android.tsx and index.ios.tsx). |
sitemap | true | Enable or disable the automatically generated sitemap at /_sitemap. |
partialRouteTypes | true | Enable partial typed routes generation. This allows TypeScript to provide type checking for routes without requiring all routes to be statically known. |
redirects | undefined | An array of static redirect rules. Each rule should have |
rewrites | undefined | An array of static rewrite rules. Each rule should have |
headers | undefined | A list of headers that are set on every route response from the server. The value can be a string or an array of strings. |
disableSynchronousScreensUpdates | false | Disable synchronous layout updates for native screens. This can help with performance in some cases. |
unstable_useServerMiddleware | false | Experimental Enable server middleware support with a |
unstable_useServerDataLoaders | false | Experimental Enable data loader support. This is only supported for |
unstable_useServerRendering | false | Experimental Enable server-side rendering. When enabled with |
Usage
For information core concepts, notation patterns, navigation layouts, and common navigation patterns, start with Router 101 section:
APIs
| API | Description |
|---|---|
| Stack | Stack navigator, toolbar, and screen components |
| Link | Link and Redirect components |
| Color | Platform color utilities |
| Native Tabs | Native tab navigation |
| Split View | Split view layout |
| UI | Headless tab components |
API
import { useRouter, Tabs, Navigator, Slot } from 'expo-router';
Components
Type: React.Element<BadgeProps>
Type: React.Element<ErrorBoundaryProps>
Type: React.Element<LabelProps>
Type: React.Element<Omit<NavigatorProps<any>, 'children'>>
Renders the currently selected content.
There are actually two different implementations of <Slot/>:
- Used inside a
_layoutas theNavigator - Used inside a
Navigatoras 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.
Type: React.Element<VectorIconProps<NameT>>
Helper component for loading vector icons.
Prefer using the md and sf props on Icon rather than using this component directly.
Only use this component when you need to load a specific icon from a vector icon family.
Example
import { Icon, VectorIcon } from 'expo-router'; import MaterialCommunityIcons from '@expo/vector-icons/MaterialCommunityIcons'; <Icon src={<VectorIcon family={MaterialCommunityIcons} name="home" />} />
{
getImageSource: (name: NameT, size: number, color: ColorValue) => Promise<ImageSourcePropType | null>
}The family of the vector icon.
Example
import MaterialCommunityIcons from '@expo/vector-icons/MaterialCommunityIcons';
Type: React.Element<ScreenProps<TabsProps, TabNavigationState<ParamListBase>, BottomTabNavigationEventMap>>
Constants
Type: {
addListener: (eventType: EventType, callback: (event: Payload<EventType>) => void) => () => void,
emit: (type: EventType, event: Payload<EventType>) => void,
enable: () => void,
isEnabled: () => boolean,
saveCurrentPathname: () => void,
}
Hooks
| Parameter | Type | Description |
|---|---|---|
| effect | EffectCallback | 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.
voidExample
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 </>; }
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.
RouteParams<TRoute> & TParamsExample
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>; }
Returns the result of the loader function for the calling route.
LoaderFunctionResult<T>Example
import { Text } from 'react-native'; import { useLoaderData } from 'expo-router'; export function loader() { return Promise.resolve({ foo: 'bar' }}; } export default function Route() { const data = useLoaderData<typeof loader>(); // { foo: 'bar' } return <Text>Data: {JSON.stringify(data)}</Text>; }
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.
RouteParams<TRoute> & TParamsExample
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>; }
| Parameter | Type | Description |
|---|---|---|
| parent(optional) | string | HrefObject | Provide an absolute path such as |
Returns the underlying React Navigation navigation object
to imperatively access layout-specific functionality like navigation.openDrawer() in a
Drawer layout.
TThe navigation object for the current route.
See: React Navigation documentation on navigation dependent functions for more information.
Example
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
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.
NavigationContainerRefWithCurrent<RootParamList>The root <NavigationContainer /> ref for the app. The ref.current may be null
if the <NavigationContainer /> hasn't mounted yet.
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.
stringExample
import { Text } from 'react-native'; import { usePathname } from 'expo-router'; export default function Route() { // pathname = "/profile/baconbrix" const pathname = usePathname(); return <Text>Pathname: {pathname}</Text>; }
Deprecated: Use
useNavigationContainerRefinstead, which returns a Reactref.
NavigationContainerRef<RootParamList> | nullReturns the navigation state of the navigator which contains the current screen.
Readonly<undefined>Example
import { useRootNavigationState } from 'expo-router'; export default function Route() { const { routes } = useRootNavigationState(); return <Text>{routes[0].name}</Text>; }
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]"].
RouteSegments<TSegments>Example
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']>()
SitemapType | nullMethods
Element| Parameter | Type | Description |
|---|---|---|
| Nav | T | The navigator component to wrap. |
| processor(optional) | (options: ScreenProps[]) => ScreenProps[] | A function that processes the screens before passing them to the navigator. |
| useOnlyUserDefinedScreens(optional) | boolean | If true, all screens not specified as navigator's children will be ignored. Default: false |
Returns a navigator that automatically injects matched routes and renders nothing when there are no children.
Return type with children prop optional.
Enables use of other built-in React Navigation navigators and other navigators built with the React Navigation custom navigator API.
Component<PropsWithoutRef<PickPartial<ComponentProps<T>, 'children'>>> & {
Protected: FunctionComponent<ProtectedProps>,
Screen: (props: ScreenProps<TOptions, TState, TEventMap>) => null
}Example
import { ParamListBase, TabNavigationState } from "@react-navigation/native"; import { createMaterialTopTabNavigator, MaterialTopTabNavigationOptions, MaterialTopTabNavigationEventMap, } from "@react-navigation/material-top-tabs"; import { withLayoutContext } from "expo-router"; const MaterialTopTabs = createMaterialTopTabNavigator(); const ExpoRouterMaterialTopTabs = withLayoutContext< MaterialTopTabNavigationOptions, typeof MaterialTopTabs.Navigator, TabNavigationState<ParamListBase>, MaterialTopTabNavigationEventMap >(MaterialTopTabs.Navigator); export default function TabLayout() { return <ExpoRouterMaterialTopTabs />; }
Types
Memoized callback containing the effect, should optionally return a cleanup function.
undefined | void | () => void
Literal Type: union
Acceptable values are: {string}:{string} | //{string}
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/settingsor a relative path like../settings. - object: An object with a
pathnameand optionalparams. Thepathnamecan be a full path like/profile/settingsor a relative path like../settings. The params can be an object of key-value pairs.
An Href can either be a string or an object.
Generic: T
Type: T ? T[href] : string | HrefObject
| Property | Type | Description |
|---|---|---|
| params(optional) | UnknownInputParams | Optional parameters for the route. |
| pathname | string | The path of the route. |
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.
| Property | Type | Description |
|---|---|---|
| legacy_subscribe(optional) | (listener: (url: string) => void) => undefined | void | () => void |
Useful as an alternative API when a third-party provider doesn't support Expo Router
but has support for React Navigation via 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 | null> | string | null | A special method used to process URLs in native apps. When invoked, it receives an
Its return value should be a Note that throwing errors within this method may result in app crashes. It's recommended to
wrap your code inside a
|
Literal Type: union
The list of input keys will become optional, everything else will remain the same.
| Property | Type | Description |
|---|---|---|
| destination | string | - |
| destinationContextKey | string | - |
| external(optional) | boolean | - |
| methods(optional) | string[] | - |
| permanent(optional) | boolean | - |
| source | string | - |
Literal Type: union
Acceptable values are: ./{string} | ../{string} | '..'
Type: PartialState<NavigationState> extended by:
| Property | Type | Description |
|---|---|---|
| state(optional) | ResultState | - |
Type: Exclude<Extract[pathname], RelativePathString | ExternalPathString>
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> ); }
| Property | Type | Description |
|---|---|---|
| back | () => void | Goes back in the navigation history. |
| canDismiss | () => boolean | Checks if it is possible to dismiss the current screen. Returns |
| canGoBack | () => boolean | Navigates to a route in the navigator's history if it supports invoking the |
| 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
|
| dismissTo | (href: Href, options: NavigationOptions) => void | Dismisses screens until the provided href is reached. If the href is not found, it will instead replace the current screen with the provided |
| navigate | (href: Href, options: NavigationOptions) => void | Navigates to the provided |
| prefetch | (name: Href) => void | Prefetch a screen in the background before navigating to it |
| push | (href: Href, options: NavigationOptions) => void | Navigates to the provided |
| replace | (href: Href, options: NavigationOptions) => void | Navigates to route without appending to the history. Can be used with
|
| setParams | (params: Partial<RouteInputParams<T>>) => void | Updates the current route's query params. |
| Property | Type | Description |
|---|---|---|
| dangerouslySingular(optional) | SingularOptions | - |
| 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 |
Type: boolean or object shaped as below:
(name, params) => string | undefined
string | undefined| Parameter | Type | Description |
|---|---|---|
| name(index signature) | string | - |
| params(index signature) | UnknownOutputParams | - |
| Property | Type | Description |
|---|---|---|
| children | SitemapType[] | - |
| contextKey | string | - |
| filename | string | - |
| href | string | Href | - |
| isGenerated | boolean | - |
| isInitial | boolean | - |
| isInternal | boolean | - |