expo-router

Patch Changes

• Fix a deep link to a screen inside an existing navigator, such as a tab, stacking a second copy of that navigator on top of a presented modal or sheet instead of returning to it. Inside nested stacks a deep link again returns to a screen that is already there, as it did before SDK 58.

Patch Changes

• Upgrade React Native to 0.88.0.

• Disable automatic safe-area measurements on web to preserve streamed content during hydration.

• Replace ambiguous null and undefined return values with RouterActionHandling enum.

• Fix a crash when swiping the drawer on React Native 0.88.

• [iOS] Use native header appearance on iOS 26+ by default. Call enableLegacyHeaderAppearance() to restore the previous appearance.

• Reduced the size of the generated Href type so large apps no longer fail with TS2590 (Expression produces a union type that is too complex to represent).

Patch Changes

• Upgrade react-native-screens to 4.30.0.

• Add the expo-router:action-enqueued performance mark, recorded when a navigation action is queued.

• Fixed the first push to a screen being reported as pagePreloaded.

• [Internal] Return platform-tagged icons from the NativeTabs icon converter so tab icons type-check with react-native-screens 4.30.0.

• Replace the experimental unstable_navigationEvents API with unstable_performance and unstable_PerformanceObserver.

• Added a development warning when navigation.isFocused() is called during render.

Patch Changes

• Upgrade react-native-screens to 4.29.0.

• Allow interfaces extending UnknownOutputParams to declare optional params, so an omitted query parameter can be typed as optional, e.g. interface MyParams extends UnknownOutputParams { id?: string }.

• Fix navigation.getState() returning the previous state inside a state event listener.

• Read unstable_settings.anchor only when a layout is first needed, so async routes apply anchors and startup no longer loads every layout.

• Reduce route info processing overhead.

• Point the useFocusEffect diagnostic links to the new focus handling guide.

• Pass the current pathname and params props to the +html component.

• [ios] Fix header title not adapting its color to content scrolling underneath a transparent header on iOS 26 Liquid Glass.

• Wait for the initial navigation state with Suspense.

• Fix Tabs and Drawer routes with dangerouslySingular keeping the nested navigator state of the previous ID after navigating to a new ID.

Patch Changes

• [Internal] Bump react-native-web to ~0.21.4.

• Fix the dev server error page for routes that throw during server rendering, which showed an "Internal Error" instead of the error overlay.

Patch Changes

• Remove isInitial from the SitemapType returned by useSitemap.

• Mark Stack.Toolbar as stable.

Patch Changes

• [Internal] Bump react-native-web to ~0.21.3.

• Restored the ./plugin subpath export so typed config plugins can be imported from <package>/plugin again.

• Fix platform-specific route parsing and loader keys.

• Generated route query strings now encode spaces as +, leave * unescaped, encode ~ as %7E, and write raw null values as key=.

• [Internal] Expose config plugin types.

Patch Changes

• Fix missing back animation after opening a screen from a link preview on iOS.

• Allow setting the native header's light or dark interface style per Stack screen on iOS.

• [Internal] Remove the import-mode module and read process.env.EXPO_ROUTER_IMPORT_MODE directly in useScreens.

• Fix a crash on launch in production when the app has no scheme.

• Resolve Native Tabs xcasset icon names through the iOS asset catalog so symbol sets render.

• Fixes a minor grammatical issue in the error message when NativeTabs is used on an unsupported platform.

Patch Changes

• Force-bump all packages, due to migration to changesets.

• Use unwrapDevLaunchURL from expo-linking instead of a private copy of the expo-development-client URL handling.

• Ignore the reserved __expo_* launch URL params on Expo Go and development build launch URLs, so they no longer become route search params.

• Remove obsolete fork annotations and commented-out path conversion code.

• Update Expo Router navigation guidance in API comments and diagnostics to point to Expo documentation.

New features

• Prevent browser unloads on web while usePreventRemove is active.

• Stabilize async routes on web and enable them by default. Native async routes remain experimental and opt-in.

• Add support for react-native-screens 5.0.0-alpha.3.

Bug fixes

• Derive browser history on web from router action results in reducer phase.

Others

• deprecated

  Deprecate withLayoutContext. Use integrateWithRouter instead.

Breaking changes

• breaking

  web.output: 'server' now renders HTML pages on each request instead of prerendering them during export.

New features

• Enable data loaders by default for static and server output

• Enable server rendering by default for web.output: "server"

• Add the apiRoutes config plugin option to support API routes with static rendering.

New features

• deprecated

  Add the stable expo-router/native-tabs entry point and deprecate expo-router/unstable-native-tabs.

• Stabilize unstable_integrateWithRouter and unstable_createStandardRouterNavigator as integrateWithRouter and createStandardRouterNavigator. The old names remain available as deprecated aliases.

Bug fixes

• Mock react-native-worklets in expo-router/testing-library so react-native-gesture-handler and react-native-reanimated load in Jest.

Others

• deprecated

  Deprecate initialRouteName in unstable_settings. Use anchor instead.

• Upgrade React Native to 0.88.0-rc.0

Breaking changes

• breaking

  Remove the onUnhandledAction container prop from expo-router/react-navigation.

• breaking

  Remove the onReady container prop and the ready container event.

• breaking

  Remove createStackNavigator from expo-router/js-stack. Use unstable_createStandardStackNavigator with unstable_integrateWithRouter instead.

• breaking

  Make expo-symbols an optional peer dependency. Install it to use md icons with NativeTabs.Trigger.Icon on Android.

• breaking

  Make @expo/ui an optional peer dependency. Install it to use Stack.Toolbar on Android.

• breaking

  Remove UNSTABLE_UnhandledLinkingContext from expo-router/react-navigation.

• breaking

  Remove BaseNavigationContainer export from expo-router/react-navigation.

• breaking

  Dispatch queued navigation actions in React transitions. The current screen stays visible while the destination suspends, so SuspenseFallback no longer renders for navigation-triggered suspense.

• breaking

  Remove beforeRemove, __unsafe_action__, PreventRemoveContext, and usePreventRemoveContext from expo-router/react-navigation.

• breaking

  Preserve the focused route when switching navigator types in a conditional layout.

• breaking

  Generate deterministic navigation states and route keys. Complete states from custom routers or persisted state must include routeKeySeq.

• breaking

  Defer navigation.dispatch and navigation helper actions until after commit. Use navigation.dispatchSync for synchronous dispatch; dispatch functions are no longer supported.

• breaking

  Require complete state in CommonActions.reset and remove Router.getRehydratedState from expo-router/react-navigation.

• breaking

  Remove resetRoot from NavigationContainerRef and createNavigationContainerRef.

• breaking

  Remove NavigatorScreenParams, getActionFromState, and LinkingOptions.getActionFromState from expo-router/react-navigation.

• breaking

  Represent nested navigation only as navigation state. The screen, params, and initial params are now ordinary user params.

• breaking

  Stop copying ancestor route params into descendant routes during imperative navigation, matching cold-start deep-link behavior.

• breaking

  Custom routers must return { state, affectedRouteKey } from getStateForAction instead of returning navigation state directly.

• breaking

  The freezeOnBlur screen option is disabled and screens are never frozen when blurred.

• breaking

  Remove the experimental web modal implementation. See the web modals guide.

• breaking

  Remove NavigationIndependentTree and useNavigationIndependentTree from expo-router/react-navigation. To embed an isolated navigation tree in a screen, use @react-navigation/native.

• breaking

  Remove the deprecated Link and useLinkProps exports from expo-router/react-navigation. Use Link from expo-router with an href instead.

• breaking

  Remove the deprecated navigateDeprecated action and the navigationInChildEnabled container prop from expo-router/react-navigation.

• breaking

  Remove getInitialState from the Router interface. Custom routers no longer create initial state.

• breaking

  Remove routeParamList from RouterConfigOptions and remove the RouterActionOptions type. Custom routers receive RouterConfigOptions in getStateForAction.

• breaking

  Remove the deprecated NavigationContainer export

• breaking

  Remove the static default field from DrawerNavigationState and deprecate getDrawerStatusFromState.

• breaking

  Remove the preloadedRouteKeys field from TabNavigationState.

• breaking

  Make history optional in TabNavigationState and DrawerNavigationState

• breaking

  Make navigation state type optional for custom routers.

• breaking

  Handle PUSH in tab and drawer routers instead of coercing it to NAVIGATE. Custom routers must now handle the PUSH action in getStateForAction.

• breaking

  Remove the initialParams prop from Expo Router screens and routeParamList from custom router action options.

• breaking

  Remove the initialRouteName prop from Expo Router navigators. Configure the initial route with unstable_settings.initialRouteName in the route layout instead.

• breaking

  Remove NavigationContainerRefContext fallback in useNavigation. The hook now throws when called outside a navigator, including components rendered via ExpoRoot's wrapper prop.

• breaking

  Allow key to be undefined in the Descriptor type and in routes passed to screen options, navigator screenOptions, and RouteGroupConfig.screenOptions callbacks.

• breaking

  Unify JS Tabs, TopTabs, Drawer, and headless tabs with NativeTabs - only screens declared in the layout become visible.

• breaking

  Make href: null hide JS tabs and make their routes unreachable, redirecting navigation to the initial tab.

• breaking

  Remove getStateForRouteNamesChange from the Router interface on expo-router/react-navigation. Custom routers must handle the ROUTE_NAMES_CHANGED action in getStateForAction instead.

• breaking

  Migrate the JS TopTabs navigator to the standard-navigation integration.

• breaking

  Make beforeRemove non-preventable and add removePrevented event.

• breaking

  Remove the navigationKey prop from layout <Screen> and <Group> components.

• breaking

  Remove the redirect prop from layout <Screen> components.

• breaking

  Add redirectTo to protected routes and render guarded screens as redirects instead of removing them from navigators.

• breaking

  Migrate the Drawer navigator to the standard-navigation integration.

• breaking

  Remove StackNavigationState.preloadedRoutes property and append preloaded routes to state.routes

• breaking

  Migrate the JS Tabs navigator to the standard-navigation integration.

New features

• Add a routePreloaded navigation event that reports the route affected by each committed preload.

• Add activityEnabled to navigators and screens to hide deeply nested route content with React Activity.

• Support application-defined screen options in custom standard navigators.

• Export createBaseTabProps, createNativeStackProps, createJSStackProps, createJSTabsProps, createJSTopTabsProps, and createNativeTabsProps for integrating navigators with Expo Router.

• Export createBaseStackProps for integrating custom stack navigators with Expo Router.

• Expose route removal prevention state to custom navigators through createProps.

• Expose route preload state to custom navigators through createProps.

• Export usePreventRemove from expo-router and add repeat for continuing the blocked navigation action.

• Add extendRouter and extendRouterActions for customizing router behavior.

• Add unstable APIs for integrating custom native and JavaScript stack navigators with standard-navigation.

• Add LocaleProvider to customize navigation direction at runtime.

• [Android] Add cornerRadius support to dropdown menu.

• Add unstable_useIsNavigating for observing queued or pending navigation.

• Add unstable NavigationAwareActivity component.

• Add screen error boundaries

• Export NativeStackView for custom navigator implementations on web.

• Add global registry for routers.

• Improve withLayoutContext types

• Expose unstable_nativeProps props from Stack component

• Expose route provenance to custom navigators through descriptor routeSource.

• Re-export drawer content components and types (DrawerContentScrollView, DrawerItem, DrawerItemList, DrawerContentComponentProps, DrawerNavigationProp, and more) from expo-router/drawer

• Add pageHeaders config plugin option for declaring per-path response headers

• Improve standard-navigation types for createProps.

• Add a processScreens option to the standard-navigation integration.

• Hide the splash screen when the built-in +not-found screen renders

• Honor loader Cache-Control headers via the platform HTTP cache instead of caching loader data in memory

• Cancel pending loader requests when their routes are removed during navigation

• Add a public expo-router/native-stack subpath so createNativeStackNavigator can be imported without a deep build/ path.

Bug fixes

• [ios] Fix link previews failing to activate preloaded screens or switch native tabs, including nested stacks and repeated preview openings.

• Mark routes after the focused one as preloaded in states returned by the singular Stack router.

• Remove guarded history entries from JavaScript and experimental stacks.

• Test not-found routes in navigators.

• Test createProps dispatch timing.

• Re-export missing bottom tab types from expo-router/js-tabs.

• Oder tabs by .Trigger order during initial render

• Prevent Native Tabs from remounting the focused tab while preloading other tabs after a cold-start deep link.

• Re-export the vendored JavaScript stack API from expo-router/js-stack.

• Fix useLoaderData() throwing "Update hook called on initial render" when React replays a suspended route after its loader settles during a transition.

• Make layouts with explicitly declared screens honor unstable_settings.initialRouteName instead of declaration order, which can change deep-link back stacks.

• Prevent unfocused nested native tab navigators from redirecting global router state.

• Fixed Tabs and TopTabs (expo-router/js-tabs, expo-router/js-top-tabs) not being usable from RSC

• Redirect fully guarded navigators to parent

• Unset nativeContainerStyle in transparent presentations

• [ios] Fix broken navigation state when a long press on a Link with a menu is released before the context menu fully presents.

• [android] Disable safe area insets in Native Tabs on Android when tab bar is hidden.

• [ios] Fix memory leaks in the native toolbar and link preview from strong-reference cycles and closures that strongly captured self.

• [android][ios] Fix expo-router/head and expo-router/stack resolution on native platforms.

• Fix missing subpath warning from Metro when importing from expo-router/server

• Fix replace navigation in tabs leaving the replaced route in history.

• Prevent useLoaderData() from re-rendering readers of unrelated loader paths

• Fix package export for expo-router/unstable-split-view

• [ios][native-tabs] Fix a [RNScreens] icon and selectedIcon must be same type. crash when the normal and selected icons resolved to different rendering modes.

Others

• Clarify prefetch terminology.

• Add batched navigation history tests.

• Replace the escape-string-regexp dependency with an internal helper.

• Replace the internal color dependency with @react-native/normalize-colors.

• Resolve queued navigation actions against render-time state.

• Propagate prevent-remove guards to ancestors.

• Mark preloaded routes with isPreloaded: true on the route object.

• Replace latest-value refs with useLatestCallback and useEffectEvent.

• removed

  Remove the root options event, DocumentTitleOptions, and the documentTitle prop from expo-router/react-navigation.

• Remove onStateChange from BaseNavigationContainer and NavigationContainerProps in expo-router/react-navigation

• Pass toolbar menu icons straight to react-navigation instead of converting them to react-native-screens icons.

• Remove module-level mutable navigation state from Expo Router.

• Remove the dev-only stack field from the __unsafe_action__ event in expo-router/react-navigation.

• Read navigation state from the React tree instead of imperative refs.

• Scope routing queues to each router root and bind useRouter() to its owning container.

• Derive useIsFocused from context.

• Base useNavigationState on global state.

• Move Expo Router store values into React context.

• removed

  Remove the ignored linking.enabled option.

• Build the complete initial navigation state from a deep link.

• Rename the routing queue intent ROUTER_LINK to NAVIGATE_TO_HREF and add a generic ACTION intent for raw navigation actions.

• Render only the focused tab route during the first render.

• Order JS Tabs, NativeTabs, headless tabs and Drawer by routeNames order

• Integrate native stack with standard navigation

• Refactor native-stack for compliance with standard-navigation integration

• removed

  Remove the deprecated static-navigation API from expo-router/react-navigation.

• Remove UNSTABLE_routeNamesChangeBehavior and unhandled-state replay from useNavigationBuilder.

• Remove useOnlyUserDefinedScreens from withLayoutContext

• Move @testing-library/jest-dom and @testing-library/user-event from dependencies to devDependencies

• Rewrite native tabs using standard-navigation

• [Internal] Split useLoaderData() into a document cache and a per-mount Suspense store

• [Internal] Read the development server URL from expo/internal/bundle-origin instead of duplicating its accessor

• [Internal] Isolate the loader's Suspense store from LoaderClient

• removed

  [Internal] Remove legacy root entrypoint shims

• Drop fast-deep-equal and shallowequal dependencies

• Drop invariant dependency