expo-router API

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.

Expo Router guides — Learn about Expo Router basics, navigation patterns, core concepts, and more.

In SDK 56 and later, Expo Router no longer supports importing from external @react-navigation/* packages in application code. Repoint those imports to the matching expo-router entry points. Run the codemod or follow the SDK 55 to 56 migration guide to update your project.

Installation

To use Expo Router in your project, you need to install. Follow the instructions from the Expo Router's installation guide:

Install Expo Router — 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

Usage

For information core concepts, notation patterns, navigation layouts, and common navigation patterns, start with Router 101 section:

Router 101

APIs

API

import { useRouter, Tabs, Navigator, Slot } from 'expo-router';

Components

Badge

Type: React.Element<BadgeProps>

BadgeProps

Inherited props

• NativeTabsTriggerBadgeProps
• StackToolbarBadgeProps

ErrorBoundary

Type: React.Element<ErrorBoundaryProps>

Props passed to a page's ErrorBoundary export.

ErrorBoundaryProps

error

Type: Error

The error that was thrown.

retry

Type: () => Promise<void>

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

ExperimentalStack

Type: React.Element<Omit<Omit<ExperimentalStackNavigatorProps, 'children' | 'initialRouteName' | 'layout' | 'screenListeners' | 'screenOptions' | 'screenLayout' | 'UNSTABLE_router' | 'UNSTABLE_routeNamesChangeBehavior' | 'id'> & DefaultRouterOptions<string> & { children: ReactNode; layout?: ((props: { state: StackNavigationState<ParamListBase>; navigation: NavigationHelpers<ParamListBase, {}>; descriptors: Record<...>; children: ReactNode; }) => ReactElement<...>) | undefined; ... 4 more ...; UNSTABLE_routeNamesChangeBehavior?: "firstMatch" | ... 1 more ... | undefined; ..., 'children'> & Partial<Pick<Omit<ExperimentalStackNavigatorProps, 'children' | 'initialRouteName' | 'layout' | 'screenListeners' | 'screenOptions' | 'screenLayout' | 'UNSTABLE_router' | 'UNSTABLE_routeNamesChangeBehavior' | 'id'> & DefaultRouterOptions<string> & { children: ReactNode; layout?: ((props: { state: StackNavigationState<ParamListBase>; navigation: NavigationHelpers<ParamListBase, {}>; descriptors: Record<...>; children: ReactNode; }) => ReactElement<...>) | undefined; ... 4 more ...; UNSTABLE_routeNamesChangeBehavior?: "firstMatch" | ... 1 more ... | undefined; ..., 'children'>>>

Renders the new react-native-screens/experimental native stack.

Sibling to Stack. Native-only — on web it falls back to the standard Stack. Opt-in per navigator: replace <Stack /> with <ExperimentalStack /> in the specific layout you want to migrate.

Icon

Type: React.Element<IconProps>

IconProps

Inherited props

• NativeTabsTriggerIconProps
• StackToolbarIconProps

Label

Type: React.Element<LabelProps>

LabelProps

Inherited props

• NativeTabsTriggerLabelProps
• StackToolbarLabelProps

ScrollViewStyleReset

Type: React.Element<React.FC>

Root style-reset for full-screen React Native web apps with a root <ScrollView /> should use the following styles to ensure native parity. See React Native for Web's root element setup.

Sitemap

Type: React.Element<React.FC>

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.

SuspenseFallback

Type: React.Element<SuspenseFallbackProps>

Props passed to a route's SuspenseFallback export.

SuspenseFallbackProps

params

Type: Record<string, string | string[]>

The route's URL parameters.

Example

{ id: "123" } // For a route `./profile/[id].tsx` navigated to as `/profile/123`

route

Type: string

The route module's contextKey.

Example

./index.tsx ./profile/[id].tsx

Tabs

Renders a tabs navigator.

ThemeProvider

Type: React.Element<Props>

VectorIcon

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" />} />

VectorIconProps

family

Type: { getImageSource: (name: NameT, size: number, color: ColorValue) => Promise<ImageSourcePropType | null> }

The family of the vector icon.

Example

import MaterialCommunityIcons from '@expo/vector-icons/MaterialCommunityIcons';

name

Type: NameT

The name of the vector icon.

ExperimentalStack.Screen

Type: React.Element<StackScreenProps>

Tabs.Screen

Type: React.Element<ScreenProps<TabsProps, TabNavigationState<ParamListBase>, BottomTabNavigationEventMap>>

ExperimentalStack.Screen.BackButton

Type: React.Element<StackScreenBackButtonProps>

Component to configure the back button.

Can be used inside Stack.Screen in a layout or directly inside a screen component.

Example

import { Stack } from 'expo-router';

export default function Layout() {
  return (
    <Stack>
      <Stack.Screen name="detail">
        <Stack.Screen.BackButton displayMode="minimal">Back</Stack.Screen.BackButton>
      </Stack.Screen>
    </Stack>
  );
}

Example

import { Stack } from 'expo-router';

export default function Page() {
  return (
    <>
      <Stack.Screen.BackButton hidden />
      <ScreenContent />
    </>
  );
}

Note: If multiple instances of this component are rendered for the same screen, the last one rendered in the component tree takes precedence.

ExperimentalStack.Screen.Title

Deprecated: Use Stack.Title instead.

Type: React.Element<StackTitleProps>

Constants

DarkTheme

Type: Theme

DefaultTheme

Type: Theme

unstable_navigationEvents

Type: { addListener: (eventType: EventType, callback: (event: Payload<EventType>) => void) => () => void, emit: (type: EventType, event: Payload<EventType>) => void, enable: () => void, isEnabled: () => boolean }

Hooks

useCurrentRouteInfo()

Returns route info for a screen it is called from.

Returns: UrlObject | undefined

useFocusEffect(effect, do_not_pass_a_second_prop)

Hook to run an effect whenever a route is focused.

• Similar to 0, but the effect re-runs each time the screen comes into focus, and the optional cleanup function runs when the screen loses focus — not on unmount.
• This makes it the right primitive for refetching data, restarting subscriptions, or resetting transient screen state every time a user returns to the route.

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 </>;
}

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: RouteOutputParams<TRoute> & TParams

Example

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>;
}

useIsFocused()

Hook to get the current focus state of the screen. Returns a true if screen is focused, otherwise false. This can be used if a component needs to render something based on the focus state.

Returns: boolean

useLoaderData()

Returns the result of the loader function for the calling route.

Returns: 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>;
}

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: RouteOutputParams<TRoute> & TParams

Example

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>;
}

useNavigation(parent)

Returns the navigation object for the current route.

• Mirrors the React Navigation 0 object.
• Use it to imperatively access layout-specific functionality like navigation.openDrawer() in a Drawer layout.

Returns: T

The navigation object for the current route.

See: The full navigation API is available directly from expo-router — no @react-navigation/* install required. For the navigator-dependent functions reference, see navigation dependent functions.

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.

useNavigationContainerRef()

Returns: NavigationContainerRefWithCurrent<RootParamList>

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

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

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>;
}

useRootNavigation()

Deprecated: Use useNavigationContainerRef instead, which returns a React ref.

Returns: NavigationContainerRef<RootParamList> | null

useRootNavigationState()

Returns the navigation state of the root navigator — the top-level navigator that contains the current screen.

Returns: NavigationState

The current NavigationState of the root navigator.

See: React Navigation's navigation state reference for the shape of the returned object.

Example

import { useRootNavigationState } from 'expo-router';

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

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

useRoute()

Hook to access the route prop of the parent screen anywhere.

Returns: T

Route prop of the parent screen.

useRoutePath()

Hook to get the path for the current route based on linking options.

Returns: string | undefined

Path for the current route.

useRouter()

Returns the Router object for imperative navigation.

Returns: ImperativeRouter

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>
 );
}

useScrollToTop(ref)

Returns: void

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]"].

Returns: 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']>()

useServerDocumentContext()

Returns the server document data for server-side rendering, including <html>/<body> attributes and additional nodes to add to <head>/<body> for metadata and assets.

Returns: ServerDocumentData

Example

import { useServerDocumentContext } from 'expo-router/html';

export default function Root({ children }) {
  const { htmlAttributes, bodyAttributes, headNodes, bodyNodes } = useServerDocumentContext();
  return (
    <html {...htmlAttributes}>
      <head>{headNodes}</head>
      <body {...bodyAttributes}>
        {children}
        {bodyNodes}
      </body>
    </html>
  );
}

useSitemap()

Returns: SitemapType | null

useTheme()

Returns: Theme

Methods

StackRouter(options)

StackRouter is considered an internal implementation and its behavior may change without a notice between expo-router's version

Returns: Router<StackNavigationState<ParamListBase>, Action | StackActionType>

TabRouter(args)

TabRouter is considered an internal implementation and its behavior may change without a notice between expo-router's version

Returns: Router<TabNavigationState<ParamListBase>, Action | TabActionType>

unstable_createStandardRouterNavigator(NavigatorContent, router, options)

This API is unstable and may change between minor releases.

Creates a standard-navigation navigator and wires it into Expo Router in one step. Use unstable_integrateWithRouter instead if you already have a navigator from createStandardNavigator.

Returns: Component<PropsWithoutRef<PickPartial<StandardRouterNavigatorProps<State, NavigatorOptions, EventMap, NavigatorProps, RouterOptions>, 'children'>>> & { Protected: FunctionComponent<ProtectedProps>, Screen: (props: ScreenProps<NavigatorOptions, State, EventMap & EventMapBase>) => null }

Example

import { unstable_createStandardRouterNavigator, TabRouter } from 'expo-router';

export const Tabs = unstable_createStandardRouterNavigator(MyTabsContent, TabRouter);

unstable_integrateWithRouter(navigator, router, options)

This API is unstable and may change between minor releases.

Wires an existing standard-navigation navigator into Expo Router, returning a navigator component (with a .Screen child) usable as a layout. Use unstable_createStandardRouterNavigator to create and integrate in one step.

Returns: Component<PropsWithoutRef<PickPartial<StandardRouterNavigatorProps<State, NavigatorOptions, EventMap, NavigatorProps, RouterOptions>, 'children'>>> & { Protected: FunctionComponent<ProtectedProps>, Screen: (props: ScreenProps<NavigatorOptions, State, EventMap & EventMapBase>) => null }

Example

import { createStandardNavigator } from 'standard-navigation';
import { unstable_integrateWithRouter, TabRouter } from 'expo-router';

const navigator = createStandardNavigator(MyTabsContent);
export const Tabs = unstable_integrateWithRouter(navigator, TabRouter);

withLayoutContext(Nav, processor, useOnlyUserDefinedScreens)

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.

Returns: 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 />;
}

Interfaces

ActionDispatchedEvent

IntegrateWithRouterOptions

createProps: ({ state, dispatch }) => ({
  activeRouteKey: state.routes[state.index].key,
  preload: (name: string) => dispatch({ type: 'PRELOAD', payload: { name } }),
})

| | useOnlyUserDefinedScreens(optional) | boolean | When true, only screens explicitly declared as <Navigator.Screen> children are rendered; routes discovered from the filesystem that were not declared are ignored. |

PageBlurredEvent

Extends: BasePageEvent

PageFocusedEvent

Extends: BasePageEvent

PagePreloadedEvent

Extends: BasePageEvent

The page rendered as part of a preload (e.g. router.prefetch()) and is not currently focused. If the user later navigates to this route, the matching pageFocused will fire then; the preload may also be invalidated or the route unmounted (pageRemoved) without a focus.

PageRemoved

Extends: BasePageEvent

Types

AnalyticsEvent

Literal type: union

Acceptable values are: PagePreloadedEvent | PageFocusedEvent | PageBlurredEvent | PageRemoved | ActionDispatchedEvent

EffectCallback()

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

Returns:

undefined | void | () => void

ExperimentalStackNavigationEventMap

Navigator-level events emitted by ExperimentalStack. Mirrors the subset of NativeStackNavigationEventMap that the gamma Stack.Screen lifecycle callbacks can drive.

ExperimentalStackNavigationOptions

Options accepted by ExperimentalStack screens. Mirrors the narrow option surface of the gamma <Stack.HeaderConfig> component from react-native-screens/experimental. Anything outside this shape is dropped with a __DEV__ warning at runtime.

ExperimentalStackNavigationProp

Literal type: union

Acceptable values are: NavigationProp<ParamList, RouteName, NavigatorID, StackNavigationState<ParamList>, ExperimentalStackNavigationOptions, ExperimentalStackNavigationEventMap> | StackActionHelpers<ParamList>

ExternalPathString

Literal type: union

Acceptable values are: {string}:{string} | //{string}

Href<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.

An Href can either be a string or an object.

Generic: T

Type: T ? T[href] : string | HrefObject

HrefObject

ImperativeRouter

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>
 );
}

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.

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

.

• Its return value should be a string, a Promise<string | null>, or null.
• When a falsy value is returned (for example, null), no redirection occurs and the app stays on the current path.
• 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. |

NativeStackHeaderItem

Literal type: union

An item that can be displayed in the header. It can be a button, a menu, spacing, or a custom element.

On iOS 26, when showing items on the right side of the header, if the items don't fit the available space, they will be collapsed into a menu automatically. Items with type: 'custom' will not be included in this automatic collapsing behavior.

Acceptable values are: NativeStackHeaderItemButton | NativeStackHeaderItemMenu | NativeStackHeaderItemSpacing | NativeStackHeaderItemCustom

NativeStackHeaderItemButton

A button item in the header.

Type: SharedHeaderItem extended by:

NativeStackHeaderItemCustom

A custom item to display any React Element in the header.

NativeStackHeaderItemMenu

An item that shows a menu when pressed.

Type: SharedHeaderItem extended by:

NativeStackHeaderItemMenuAction

An action item in a menu.

NativeStackHeaderItemMenuSubmenu

A submenu item that contains other menu items.

• default: menu items are displayed normally.
• palette: menu items are displayed in a horizontal row.

.

• Defaults to default.
• Read more: https://developer.apple.com/documentation/uikit/uimenu/options-swift.struct/displayaspalette | | multiselectable(optional) | boolean | Whether multiple items in the submenu can be selected, i.e. in "on" state.
• Defaults to false.
• Read more: https://developer.apple.com/documentation/uikit/uimenu/options-swift.struct/singleselection | | type | 'submenu' | - |

NativeStackHeaderItemSpacing

An item to add spacing between other items in the header.

NativeStackNavigationEventMap

• index - current detent index in the sheetAllowedDetents array,
• stable - on Android false value means that the user is dragging the sheet or it is settling; on iOS it is always true.

| | transitionEnd | { data: { closing: boolean } } | Event which fires when a transition animation ends. | | transitionStart | { data: { closing: boolean } } | Event which fires when a transition animation starts. |

NativeStackNavigationOptions

• "default": use the platform default animation
• "fade": fade screen in or out
• "fade_from_bottom" – performs a fade from bottom animation
• "flip": flip the screen, requires presentation: "modal" (iOS only)
• "simple_push": use the platform default animation, but without shadow and native header transition (iOS only)
• "slide_from_bottom": slide in the new screen from bottom
• "slide_from_right": slide in the new screen from right (Android only, uses default animation on iOS)
• "slide_from_left": slide in the new screen from left (Android only, uses default animation on iOS)
• "ios_from_right" - iOS like slide in animation. pushes in the new screen from right to left (Android only, resolves to default transition on iOS)
• "ios_from_left" - iOS like slide in animation. pushes in the new screen from left to right (Android only, resolves to default transition on iOS)
• "none": don't animate the screen

. Only supported on iOS and Android. | | animationDuration(optional) | number | Duration (in milliseconds) for the following transition animations on iOS|

• slide_from_bottom
• fade_from_bottom
• fade
• simple_push

. Defaults to 500. The duration is not customizable for:

• Screens with default and flip animations
• Screens with presentation set to modal, formSheet, pageSheet (regardless of animation)

| | animationMatchesGesture(optional) | boolean | Whether the gesture to dismiss should use animation provided to animation prop.

• Defaults to false.

• Doesn't affect the behavior of screens presented modally. | | animationTypeForReplace(optional) | ScreenProps[replaceAnimation] | The type of animation to use when this screen replaces another screen.

• Defaults to pop.

• Supported values|

• "push": the new screen will perform push animation.

• "pop": the new screen will perform pop animation.

.

• Only supported on iOS and Android. | | autoHideHomeIndicator(optional) | boolean | Whether the home indicator should prefer to stay hidden on this screen.

• Defaults to false. | | contentStyle(optional) | StyleProp<ViewStyle> | Style object for the scene content. | | freezeOnBlur(optional) | boolean | Whether inactive screens should be suspended from re-rendering.

• Defaults to false.

• Defaults to true when enableFreeze() is run at the top of the application.

• Requires react-native-screens version >=3.16.0.

• Only supported on iOS and Android. | | fullScreenGestureEnabled(optional) | boolean | Whether the gesture to dismiss should work on the whole screen.

• The behavior depends on iOS version.

• On iOS 18 and below: false by default.

• If enabled, swipe gesture will use simple_push transition animation by default.

• It can be changed with animation & animationMatchesGesture props, but default iOS swipe animation is not achievable.

• On iOS 26 and up: true by default to match new native behavior.

• You can still customize it with animation & animationMatchesGesture props.

• Doesn't affect the behavior of screens presented modally. | | fullScreenGestureShadowEnabled(optional) | boolean | Deprecated: since iOS 26. iOS 18 and below.

• Controls whether the full screen dismiss gesture has shadow under view during transition.

• The gesture uses custom transition and thus doesn't have a shadow by default.

• When enabled, a custom shadow view is added during the transition which tries to mimic the default iOS shadow.

• Defaults to true.

• This does not affect the behavior of transitions that don't use gestures, enabled by fullScreenGestureEnabled prop. | | gestureDirection(optional) | ScreenProps[swipeDirection] | Sets the direction in which you should swipe to dismiss the screen.

• When using vertical option, options fullScreenGestureEnabled: true, animationMatchesGesture: true and animation: 'slide_from_bottom' are set by default.

• Supported values|

• vertical – dismiss screen vertically

• horizontal – dismiss screen horizontally (default)

| | gestureEnabled(optional) | boolean | Whether you can use gestures to dismiss this screen.

• Defaults to true.

• Only supported on iOS. | | gestureResponseDistance(optional) | ScreenProps[gestureResponseDistance] | Use it to restrict the distance from the edges of screen in which the gesture should be recognized.

• To be used alongside fullScreenGestureEnabled. | | header(optional) | (props: NativeStackHeaderProps) => React.ReactNode | Function that given HeaderProps returns a React Element to display as a header. | | headerBackButtonDisplayMode(optional) | ScreenStackHeaderConfigProps[backButtonDisplayMode] | How the back button displays icon and title.

• Supported values|

• "default" - Displays one of the following depending on the available space: previous screen's title, generic title (e.g. 'Back') or no title (only icon).

• "generic" – Displays one of the following depending on the available space: generic title (e.g. 'Back') or no title (only icon).

• "minimal" – Always displays only the icon without a title.

. The space-aware behavior is disabled when:

• The iOS version is 13 or lower
• Custom font family or size is set (e.g. with headerBackTitleStyle)
• Back button menu is disabled (e.g. with headerBackButtonMenuEnabled)

.

• In such cases, a static title and icon are always displayed.

• Defaults to "default" on iOS, and "minimal" on other platforms.

• Only supported on iOS and Web. | | headerBackButtonMenuEnabled(optional) | boolean | Boolean indicating whether to show the menu on longPress of iOS >= 14 back button.

• Defaults to true.

• Requires react-native-screens version >=3.3.0.

• Only supported on iOS. | | headerBackground(optional) | () => React.ReactNode | Function which returns a React Element to render as the background of the header.

• This is useful for using backgrounds such as an image, a gradient, blur effect etc. You can use this with headerTransparent to render content underneath a translucent header. | | headerBackIcon(optional) | { source: ImageSourcePropType, type: 'image' } | Icon to display in the header as the icon in the back button.

• Defaults to back icon image for the platfor|

• A chevron on iOS

• An arrow on Android

. Example.

headerBackIcon: {
  type: 'image',
  source: require('./back-icon.png'),
}

| | headerBackImageSource(optional) | ImageSourcePropType | Deprecated: Use headerBackIcon instead.

• Image to display in the header as the icon in the back button. | | headerBackTitle(optional) | string | Title string used by the back button on iOS.

• Defaults to the previous scene's title.

• On iOS the text might be shortened to "Back" or arrow icon depending on the available space, following native iOS behaviour.

• See headerBackButtonDisplayMode to read about limitations and interactions with other props.

• Use headerBackButtonDisplayMode: "minimal" to hide it.

• Only supported on iOS and Web. | | headerBackTitleStyle(optional) | StyleProp<{ fontFamily: string, fontSize: number }> | Style object for header back title.

• Supported properties|

• fontFamily

• fontSize

.

• Only supported on iOS and Web. | | headerBackVisible(optional) | boolean | Whether the back button is visible in the header.

• You can use it to show a back button alongside headerLeft if you have specified it.

• This will have no effect on the first screen in the stack. | | headerBlurEffect(optional) | ScreenStackHeaderConfigProps[blurEffect] | Blur effect for the translucent header.

• The headerTransparent option needs to be set to true for this to work. Note: Using both headerBlurEffect and scrollEdgeEffects (>= iOS 26) simultaneously may cause overlapping effects.

• Only supported on iOS. | | headerLargeStyle(optional) | StyleProp<{ backgroundColor: ColorValue }> | Style of the header when a large title is shown.

• The large title is shown if headerLargeTitle is true and the edge of any scrollable content reaches the matching edge of the header.

• Supported properties|

• backgroundColor

.

• Only supported on iOS. | | headerLargeTitle(optional) | boolean | Deprecated: Use headerLargeTitleEnabled instead.

• Whether to enable header with large title which collapses to regular header on scroll. | | headerLargeTitleEnabled(optional) | boolean | Whether to enable header with large title which collapses to regular header on scroll.

• For large title to collapse on scroll, the content of the screen should be wrapped in a scrollable view such as ScrollView or FlatList.

• If the scrollable area doesn't fill the screen, the large title won't collapse on scroll.

• You also need to specify contentInsetAdjustmentBehavior="automatic" in your ScrollView, FlatList etc. Only supported on iOS. | | headerLargeTitleShadowVisible(optional) | boolean | Whether drop shadow of header is visible when a large title is shown.

• Only supported on iOS. | | headerLargeTitleStyle(optional) | StyleProp<{ color: ColorValue, fontFamily: string, fontSize: number, fontWeight: string }> | Style object for large title in header.

• Supported properties|

• fontFamily

• fontSize

• fontWeight

• color

.

• Only supported on iOS. | | headerLeft(optional) | (props: NativeStackHeaderBackProps) => React.ReactNode | Function which returns a React Element to display on the left side of the header.

• This replaces the back button.

• See headerBackVisible to show the back button along side left element.

• Will be overriden by headerLeftItems on iOS. | | headerRight(optional) | (props: NativeStackHeaderItemProps) => React.ReactNode | Function which returns a React Element to display on the right side of the header.

• Will be overriden by headerRightItems on iOS. | | headerSearchBarOptions(optional) | SearchBarProps | Options to render a native search bar.

• You also need to specify contentInsetAdjustmentBehavior="automatic" in your ScrollView, FlatList etc. If you don't have a ScrollView, specify headerTransparent: false. | | headerShadowVisible(optional) | boolean | Whether to hide the elevation shadow (Android) or the bottom border (iOS) on the header. | | headerShown(optional) | boolean | Whether to show the header.

• The header is shown by default.

• Setting this to false hides the header. | | headerStyle(optional) | StyleProp<{ backgroundColor: ColorValue }> | Style object for header.

• Supported properties|

• backgroundColor

| | headerTintColor(optional) | ColorValue | Tint color for the header.

• Changes the color of back button and title. | | headerTitle(optional) | string | (props: { children: string, tintColor: ColorValue }) => React.ReactNode | String or a function that returns a React Element to be used by the header.

• Defaults to screen title or route name.

• When a function is passed, it receives tintColor andchildren in the options object as an argument.

• The title string is passed in children.

• Note that if you render a custom element by passing a function, animations for the title won't work. | | headerTitleAlign(optional) | 'left' \| 'center' | How to align the header title.

• Defaults to left on platforms other than iOS.

• Not supported on iOS.

• It's always center on iOS and cannot be changed. | | headerTitleStyle(optional) | StyleProp<Pick<TextStyle, 'fontFamily' | 'fontSize' | 'fontWeight'> & { color: ColorValue }> | Style object for header title.

• Supported properties|

• fontFamily

• fontSize

• fontWeight

• color

| | headerTransparent(optional) | boolean | Boolean indicating whether the navigation bar is translucent.

• Setting this to true makes the header absolutely positioned, and changes the background color to transparent unless specified in headerStyle. | | keyboardHandlingEnabled(optional) | boolean | Whether the keyboard should hide when swiping to the previous screen.

• Defaults to false. | | orientation(optional) | ScreenProps[screenOrientation] | The display orientation to use for the screen.

• Supported values|

• "default" - resolves to "all" without "portrait_down" on iOS. On Android, this lets the system decide the best orientation.

• "all": all orientations are permitted.

• "portrait": portrait orientations are permitted.

• "portrait_up": right-side portrait orientation is permitted.

• "portrait_down": upside-down portrait orientation is permitted.

• "landscape": landscape orientations are permitted.

• "landscape_left": landscape-left orientation is permitted.

• "landscape_right": landscape-right orientation is permitted.

.

• Only supported on iOS and Android. | | presentation(optional) | Exclude<ScreenProps[stackPresentation], 'push'> | 'card' | How should the screen be presented.

• Supported values|

• "card": the new screen will be pushed onto a stack, which means the default animation will be slide from the side on iOS, the animation on Android will vary depending on the OS version and theme.

• "modal": the new screen will be presented modally. this also allows for a nested stack to be rendered inside the screen.

• "transparentModal": the new screen will be presented modally, but in addition, the previous screen will stay so that the content below can still be seen if the screen has translucent background.

• "containedModal": will use "UIModalPresentationCurrentContext" modal style on iOS and will fallback to "modal" on Android.

• "containedTransparentModal": will use "UIModalPresentationOverCurrentContext" modal style on iOS and will fallback to "transparentModal" on Android.

• "fullScreenModal": will use "UIModalPresentationFullScreen" modal style on iOS and will fallback to "modal" on Android.

• "formSheet": will use "UIModalPresentationFormSheet" modal style on iOS and will fallback to "modal" on Android.

• "pageSheet": will use "UIModalPresentationPageSheet" modal style on iOS and will fallback to "modal" on Android.

.

• Only supported on iOS and Android. | | scrollEdgeEffects(optional) | { bottom: ScrollEdgeEffect, left: ScrollEdgeEffect, right: ScrollEdgeEffect, top: ScrollEdgeEffect } | Configures the scroll edge effect for the content ScrollView (the ScrollView that is present in first descendants chain of the Screen).

• Depending on values set, it will blur the scrolling content below certain UI elements (header items, search bar) for the specified edge of the ScrollView.

• When set in nested containers, i.e. Native Stack inside Native Bottom Tabs, or the other way around, the ScrollView will use only the innermost one's config. Note: Using both headerBlurEffect and scrollEdgeEffects (>= iOS 26) simultaneously may cause overlapping effects.

• Edge effects can be configured for each edge separately.

• The following values are currently supported|

• automatic - the automatic scroll edge effect style,

• hard - a scroll edge effect with a hard cutoff and dividing line,

• soft - a soft-edged scroll edge effect,

• hidden - no scroll edge effect.

.

• Defaults to automatic for each edge. | | sheetAllowedDetents(optional) | number[] \| 'fitToContents' | Describes heights where a sheet can rest.

• Works only when presentation is set to formSheet.

• Heights should be described as fraction (a number from [0, 1] interval) of screen height / maximum detent height.

• You can pass an array of ascending values each defining allowed sheet detent. iOS accepts any number of detents, while Android is limited to three.

• There is also possibility to specify fitToContents literal, which intents to set the sheet height to the height of its contents.

• Note that the array must be sorted in ascending order.

• This invariant is verified only in developement mode, where violation results in error. Android is limited to up 3 values in the array -- any surplus values, beside first three are ignored.

• Defaults to [1.0]. | | sheetCornerRadius(optional) | number | The corner radius that the sheet will try to render with.

• Works only when presentation is set to formSheet.

• If set to non-negative value it will try to render sheet with provided radius, else it will apply system default.

• If left unset system default is used. | | sheetExpandsWhenScrolledToEdge(optional) | boolean | Whether the sheet should expand to larger detent when scrolling.

• Works only when presentation is set to formSheet.

• Defaults to true. | | sheetGrabberVisible(optional) | boolean | Boolean indicating whether the sheet shows a grabber at the top.

• Works only when presentation is set to formSheet.

• Defaults to false. | | sheetInitialDetentIndex(optional) | number \| 'last' | Index of the detent the sheet should expand to after being opened.

• Works only when stackPresentation is set to formSheet.

• If the specified index is out of bounds of sheetAllowedDetents array, in dev environment more error will be thrown, in production the value will be reset to default value.

• Additionaly there is last value available, when set the sheet will expand initially to last (largest) detent.

• Defaults to 0 - which represents first detent in the detents array. | | sheetLargestUndimmedDetentIndex(optional) | number \| 'none' \| 'last' | The largest sheet detent for which a view underneath won't be dimmed.

• Works only when presentation is set to formSheet.

• This prop can be set to an number, which indicates index of detent in sheetAllowedDetents array for which there won't be a dimming view beneath the sheet.

• Additionaly there are following options available|

• none - there will be dimming view for all detents levels,

• last - there won't be a dimming view for any detent level.

| | statusBarAnimation(optional) | ScreenProps[statusBarAnimation] | Sets the status bar animation (similar to the StatusBar component).

• On iOS, this option applies to appereance animation of the status bar.
• Requires setting View controller-based status bar appearance -> YES (or removing the config) in your Info.plist file.
• Defaults to fade on iOS and none on Android.
• Only supported on Android and iOS. | | statusBarHidden(optional) | boolean | Whether the status bar should be hidden on this screen.
• Requires setting View controller-based status bar appearance -> YES in your Info.plist file.
• Only supported on Android and iOS. | | statusBarStyle(optional) | ScreenProps[statusBarStyle] | Sets the status bar color (similar to the StatusBar component).
• Requires setting View controller-based status bar appearance -> YES (or removing the config) in your Info.plist file. auto and inverted are supported only on iOS.
• Defaults to auto on iOS and light on Android.
• Only supported on Android and iOS. | | title(optional) | string | String that can be displayed in the header as a fallback for headerTitle. | | unstable_headerLeftItems(optional) | (props: NativeStackHeaderItemProps) => NativeStackHeaderItem[] | Function which returns an array of items to display as on the left side of the header.
• Overrides headerLeft.
• This is an unstable API and might change in the future. | | unstable_headerRightItems(optional) | (props: NativeStackHeaderItemProps) => NativeStackHeaderItem[] | Function which returns an array of items to display as on the right side of the header.
• Overrides headerRight.
• This is an unstable API and might change in the future. |

NativeStackNavigationProp

Literal type: union

Acceptable values are: NavigationProp<ParamList, RouteName, NavigatorID, StackNavigationState<ParamList>, NativeStackNavigationOptions, NativeStackNavigationEventMap> | StackActionHelpers<ParamList>

NativeStackOptionsArgs

Type: NativeStackScreenProps<ParamList, RouteName, NavigatorID> extended by:

PickPartial

Literal type: union

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

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

RedirectConfig

RelativePathString

Literal type: union

Acceptable values are: ./{string} | ../{string} | '..'

ResultState

Type: PartialState<NavigationState> extended by:

RoutePath

Type: Exclude<Extract[pathname], RelativePathString | ExternalPathString>

ScreenProps

SearchOrHash

Literal type: union

Acceptable values are: ?{string} | #{string}

SingularOptions

Type: boolean or object shaped as below:

(name, params) => `string | undefined`

SitemapType

StackNavigationState

Type: NavigationState<ParamList> extended by:

StackRouterOptions

Type: DefaultRouterOptions

StandardNavigatorEventMapBase

Type: Record<string, { canPreventDefault: boolean, data: object | undefined }>

StandardUseNavigationBuilderOptions

Type: DefaultNavigatorOptions<ParamListBase, string | undefined, State, NavigatorOptions, EventMap & StandardNavigatorEventMapBase, any>

TabNavigationState

Type: Omit<NavigationState<ParamList>, 'history'> extended by:

TabRouterOptions

Type: DefaultRouterOptions extended by:

• firstRoute - return to the first defined route
• initialRoute - return to the route from initialRouteName
• order - return to the route defined before the focused route
• history - return to last visited route; if the same route is visited multiple times, the older entries are dropped from the history
• fullHistory - return to last visited route; doesn't drop duplicate entries unlike history - matches behavior of web pages
• none - do not handle going back

|

Router settings

initialRouteName

When deep linking to a route, you may want to provide a user with a "back" button. The initialRouteName sets the default screen of the stack and should match a valid filename (without the extension).

import { Stack } from 'expo-router';

export const unstable_settings = {
  // Ensure any route can link back to `/`
  initialRouteName: 'index',
};

export default function Layout() {
  return <Stack />;
}

Now deep linking directly to /other or reloading the page will continue to show the back arrow.

When using array syntax (foo,bar) you can specify the name of a group in the unstable_settings object to target a particular segment.

export const unstable_settings = {
  // Used for `(foo)`
  initialRouteName: 'first',
  // Used for `(bar)`
  bar: {
    initialRouteName: 'second',
  },
};

The initialRouteName is only used when deep-linking to a route.

• During app navigation, the route you are navigating to will be the initial route.
• To also load the initialRouteName route below the target route, use the withAnchor prop on the <Link /> component.
• The imperative APIs accept the same option.

// If this navigates to a new _layout, load the initial route below the target route
<Link href="/route" withAnchor />;

router.push('/route', { withAnchor: true });

Sitemap

On native, you can use the uri-scheme CLI to test opening native links on a device.

For example, if you want to launch the Expo Go app on iOS to the /form-sheet route, run:

bunx uri-scheme open exp://192.168.87.39:19000/--/form-sheet --ios

Replace 192.168.87.39:19000 with the IP address shown when running npx expo start.

You can also search for links directly in a browser like Safari or Chrome to test deep linking on physical devices. Learn more about testing deep links.

Sitemap

Expo Router currently injects a /_sitemap automatically that provides a list of all routes in the app. This is useful for debugging.

The sitemap can be removed by adding sitemap: false to the expo-router config plugin in the app config:

{
  "plugins": [
    [
      "expo-router",
      {
        "sitemap": false
      }
    ]
  ]
}

Screen tracking

Unlike React Navigation, Expo Router always has access to a URL. This means screen tracking is as easy as the web.

1. Create a higher-order component that observes the currently selected URL
2. Track the URL in your analytics provider

import { useEffect } from 'react';
import { usePathname, useGlobalSearchParams, Slot } from 'expo-router';

export default function Layout() {
  const pathname = usePathname();
  const params = useGlobalSearchParams();

  // Track the location in your analytics provider here.
  useEffect(() => {
    analytics.track({ pathname, params });
  }, [pathname, params]);

  // Export all the children routes in the most basic way.
  return <Slot />;
}

Now when the user changes routes, the analytics provider will be notified.

Migrating from React Navigation

React Navigation's screen tracking guide cannot make the same assumptions about the navigation state that Expo Router can.

• As a result, the implementation requires the use of onReady and onStateChange callbacks.
• Avoid using these methods if possible as the root <NavigationContainer /> is not directly exposed and allows cascading in Expo Router.

Error handling

This guide specifies how to handle unmatched routes, errors, and loading states in your app when using Expo Router.

Unmatched routes

Native apps don't have a server so there are technically no 404s. However, if you're implementing a router universally, then it makes sense to handle missing routes. This is done automatically for each app, but you can also customize it.

import { Unmatched } from 'expo-router';
export default Unmatched;

This will render the default Unmatched. You can export any component you want to render instead. We recommend having a link to / so users can navigate back to the home screen.

Route priority

1. Static files in the public directory.
2. Standard and dynamic routes in the app directory.
3. API routes in the app directory.
4. Not-found routes will be served last with a 404 status code.

Error handling

Expo Router enables fine-tuned error handling to enable a more opinionated data-loading strategy in the future.

You can export a nested ErrorBoundary component from any route to intercept and format component-level errors using React Error Boundaries:

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

export function ErrorBoundary({ error, retry }: ErrorBoundaryProps) {
  return (
    <View style={{ flex: 1, backgroundColor: "red" }}>
      <Text>{error.message}</Text>
      <Text onPress={retry}>Try Again?</Text>
    </View>
  );
}

export default function Page() { ... }

When you export an ErrorBoundary the route will be wrapped with a React Error Boundary effectively:

function Route({ ErrorBoundary, Component }) {
  return (
    <Try catch={ErrorBoundary}>
      <Component />
    </Try>
  );
}

When ErrorBoundary is not present, the error will be thrown to the nearest parent's ErrorBoundary and accepts error and retry props.

Error boundaries for screens in a layout

A screen error boundary keeps navigator UI, such as headers and tab bars, mounted when a screen throws. Configure it on a layout or navigator:

import { Stack, type ErrorBoundaryProps } from 'expo-router';
import { Text } from 'react-native';

function ScreenErrorBoundary({ error, retry }: ErrorBoundaryProps) {
  return <Text onPress={retry}>Try again: {error.message}</Text>;
}

// Configure the boundary for screens in this layout and nested layouts.
export const unstable_settings = {
  screenErrorBoundary: ScreenErrorBoundary,
};

export default function Layout() {
  return <Stack />;
}

Alternatively, configure the boundary on the navigator:

import { Stack, type ErrorBoundaryProps } from 'expo-router';
import { Text } from 'react-native';

function ScreenErrorBoundary({ error, retry }: ErrorBoundaryProps) {
  return <Text onPress={retry}>Try again: {error.message}</Text>;
}

// This prop overrides unstable_settings.screenErrorBoundary for the same screens.
export default function Layout() {
  return <Stack unstable_screenErrorBoundary={ScreenErrorBoundary} />;
}

Expo Router applies error boundaries in the following order:

1. ErrorBoundary exported from the screen
2. Navigator-level prop (for example, Stack)
3. unstable_settings.screenErrorBoundary declared in the _layout.tsx file

Nested layouts inherit unstable_settings.screenErrorBoundary unless they define their own screen error boundary. Set screenErrorBoundary to null in a nested layout to stop inheriting it.

Work in progress

React Native LogBox needs to be presented less aggressively to develop with errors. Currently, it shows for console.error and console.warn. However, it should ideally only show for uncaught errors.

Loading states with Suspense fallback

Custom suspense fallbacks are available in SDK 56 and later.

Expo Router wraps each route in a React Suspense boundary. You can export a SuspenseFallback component from a layout file to customize the loading UI shown while any child route is suspended:

import { ActivityIndicator, View } from 'react-native';
import { Stack } from 'expo-router';

export function SuspenseFallback() {
  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <ActivityIndicator size="large" />
    </View>
  );
}

export default function RootLayout() {
  return <Stack />;
}

When multiple parent layouts define a fallback, the nearest parent takes precedence.

Accessing route parameters

The SuspenseFallback component receives route and params props. You can use params to display context-specific loading states for dynamic routes, for example:

import { ActivityIndicator, Text, View } from 'react-native';
import { Stack, type SuspenseFallbackProps } from 'expo-router';

export function SuspenseFallback({ params }: SuspenseFallbackProps) {
  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <Text>Loading profile {params.id}...</Text>
      <ActivityIndicator size="large" />
    </View>
  );
}

export default function AppLayout() {
  return <Stack />;
}

Limitations

• Async routes do not support custom Suspense fallbacks.

Sources

The original Expo docs for this page:

• Router (source-of-truth/versions/v57.0.0/sdk/router.md)
• Router settings (source-of-truth/router/advanced/router-settings.md)
• Sitemap (source-of-truth/router/reference/sitemap.md)
• Screen tracking for analytics (source-of-truth/router/reference/screen-tracking.md)
• Error handling and loading states (source-of-truth/router/error-handling.md)