feat(react-router): add navigateRoot to useIonRouter

Author: ShaneK

packages/react-router/src/ReactRouter/IonRouter.tsx

@@ -655,6 +655,27 @@ export const IonRouter = ({ children, registerHistoryListener }: PropsWithChildr
     navigate(path, { replace: routeAction !== 'push' });
   };
 
+  /**
+   * Navigates to a new root path, clearing Ionic's navigation history so that
+   * canGoBack() returns false after the transition. All previously mounted views
+   * are unmounted. Useful for post-login / post-logout root navigation.
+   *
+   * @param pathname The path to navigate to.
+   * @param routeAnimation An optional custom animation builder.
+   */
+  const handleNavigateRoot = (pathname: string, routeAnimation?: AnimationBuilder) => {
+    currentTab.current = undefined;
+    forwardStack.current = [];
+
+    incomingRouteParams.current = {
+      routeAction: 'replace',
+      routeDirection: 'root',
+      routeAnimation,
+    };
+
+    navigate(pathname, { replace: true });
+  };
+
   const routeMangerContextValue: RouteManagerContextState = {
     canGoBack: () => locationHistory.current.canGoBack(),
     clearOutlet: viewStack.current.clear,
@@ -678,6 +699,7 @@ export const IonRouter = ({ children, registerHistoryListener }: PropsWithChildr
         onNativeBack={handleNativeBack}
         onNavigateBack={handleNavigateBack}
         onNavigate={handleNavigate}
+        onNavigateRoot={handleNavigateRoot}
         onSetCurrentTab={handleSetCurrentTab}
         onChangeTab={handleChangeTab}
         onResetTab={handleResetTab}

packages/react-router/src/ReactRouter/StackManager.tsx

@@ -279,6 +279,31 @@ export class StackManager extends React.PureComponent<StackManagerProps> {
     return true;
   }
 
+  /**
+   * Handles root navigation by unmounting all non-entering views in this outlet.
+   * Fires ionViewWillLeave / ionViewDidLeave only on views that are currently visible.
+   * Views that are mounted but not visible (e.g., pages earlier in the back stack)
+   * are silently unmounted without lifecycle events, consistent with the behavior
+   * of out-of-scope outlet cleanup.
+   */
+  private handleRootNavigation(enteringViewItem: ViewItem | undefined): void {
+    const allViewsInOutlet = this.context.getViewItemsForOutlet(this.id);
+    allViewsInOutlet.forEach((viewItem) => {
+      if (viewItem === enteringViewItem) {
+        return;
+      }
+      if (viewItem.ionPageElement && isViewVisible(viewItem.ionPageElement)) {
+        viewItem.ionPageElement.dispatchEvent(
+          new CustomEvent('ionViewWillLeave', { bubbles: false, cancelable: false })
+        );
+        viewItem.ionPageElement.dispatchEvent(
+          new CustomEvent('ionViewDidLeave', { bubbles: false, cancelable: false })
+        );
+      }
+      this.context.unMountViewItem(viewItem);
+    });
+  }
+
   /**
    * Handles nested outlet with relative routes but no parent path. Returns true to abort.
    */
@@ -875,8 +900,8 @@ export class StackManager extends React.PureComponent<StackManagerProps> {
     // Find entering and leaving view items
     const viewItems = this.findViewItems(routeInfo);
     let enteringViewItem = viewItems.enteringViewItem;
-    const leavingViewItem = viewItems.leavingViewItem;
-    const shouldUnmountLeavingViewItem = this.shouldUnmountLeavingView(routeInfo, enteringViewItem, leavingViewItem);
+    let leavingViewItem = viewItems.leavingViewItem;
+    let shouldUnmountLeavingViewItem = this.shouldUnmountLeavingView(routeInfo, enteringViewItem, leavingViewItem);
 
     // Get parent path for nested outlets
     const parentPath = this.getParentPath();
@@ -886,6 +911,13 @@ export class StackManager extends React.PureComponent<StackManagerProps> {
       return;
     }
 
+    // Handle root navigation: unmount all non-entering views
+    if (routeInfo.routeDirection === 'root') {
+      this.handleRootNavigation(enteringViewItem);
+      leavingViewItem = undefined;
+      shouldUnmountLeavingViewItem = false;
+    }
+
     // Clear any pending out-of-scope unmount timeout
     if (this.outOfScopeUnmountTimeout) {
       clearTimeout(this.outOfScopeUnmountTimeout);

packages/react-router/test/base/src/App.tsx

@@ -65,6 +65,7 @@ import { ParamSwipeBack, ParamSwipeBackB } from './pages/param-swipe-back/ParamS
 import TabLifecycle from './pages/tab-lifecycle/TabLifecycle';
 import TabLifecycleOutside from './pages/tab-lifecycle/TabLifecycleOutside';
 import { RouterLinkModifierClick, RouterLinkModifierClickTarget } from './pages/router-link-modifier-click/RouterLinkModifierClick';
+import { NavigateRootPageA, NavigateRootPageB, NavigateRootPageC } from './pages/navigate-root/NavigateRoot';
 
 setupIonicReact();
 
@@ -125,6 +126,9 @@ const App: React.FC = () => {
           <Route path="/tab-lifecycle-outside" element={<TabLifecycleOutside />} />
           <Route path="/router-link-modifier-click" element={<RouterLinkModifierClick />} />
           <Route path="/router-link-modifier-click/target" element={<RouterLinkModifierClickTarget />} />
+          <Route path="/navigate-root/page-a" element={<NavigateRootPageA />} />
+          <Route path="/navigate-root/page-b" element={<NavigateRootPageB />} />
+          <Route path="/navigate-root/page-c" element={<NavigateRootPageC />} />
         </IonRouterOutlet>
       </IonReactRouter>
     </IonApp>

packages/react-router/test/base/src/pages/Main.tsx

@@ -137,6 +137,9 @@ const Main: React.FC = () => {
           <IonItem routerLink="/router-link-modifier-click">
             <IonLabel>Router Link Modifier Click</IonLabel>
           </IonItem>
+          <IonItem routerLink="/navigate-root/page-a">
+            <IonLabel>Navigate Root</IonLabel>
+          </IonItem>
         </IonList>
       </IonContent>
     </IonPage>

packages/react-router/test/base/src/pages/navigate-root/NavigateRoot.tsx

@@ -0,0 +1,76 @@
+import {
+  IonContent,
+  IonHeader,
+  IonPage,
+  IonTitle,
+  IonToolbar,
+  IonButton,
+  IonButtons,
+  IonBackButton,
+  useIonRouter,
+} from '@ionic/react';
+import React from 'react';
+
+export const NavigateRootPageA: React.FC = () => {
+  const ionRouter = useIonRouter();
+
+  return (
+    <IonPage data-pageid="navigate-root-page-a">
+      <IonHeader>
+        <IonToolbar>
+          <IonButtons slot="start">
+            <IonBackButton />
+          </IonButtons>
+          <IonTitle>Page A</IonTitle>
+        </IonToolbar>
+      </IonHeader>
+      <IonContent>
+        <p id="page-a-can-go-back">{ionRouter.canGoBack() ? 'yes' : 'no'}</p>
+        <IonButton id="go-to-page-b" routerLink="/navigate-root/page-b">
+          Go to Page B
+        </IonButton>
+      </IonContent>
+    </IonPage>
+  );
+};
+
+export const NavigateRootPageB: React.FC = () => (
+  <IonPage data-pageid="navigate-root-page-b">
+    <IonHeader>
+      <IonToolbar>
+        <IonButtons slot="start">
+          <IonBackButton />
+        </IonButtons>
+        <IonTitle>Page B</IonTitle>
+      </IonToolbar>
+    </IonHeader>
+    <IonContent>
+      <IonButton id="go-to-page-c" routerLink="/navigate-root/page-c">
+        Go to Page C
+      </IonButton>
+    </IonContent>
+  </IonPage>
+);
+
+export const NavigateRootPageC: React.FC = () => {
+  const ionRouter = useIonRouter();
+
+  return (
+    <IonPage data-pageid="navigate-root-page-c">
+      <IonHeader>
+        <IonToolbar>
+          <IonButtons slot="start">
+            <IonBackButton />
+          </IonButtons>
+          <IonTitle>Page C</IonTitle>
+        </IonToolbar>
+      </IonHeader>
+      <IonContent>
+        <p id="page-c-can-go-back">{ionRouter.canGoBack() ? 'yes' : 'no'}</p>
+        <IonButton id="navigate-root-to-page-a" onClick={() => ionRouter.navigateRoot('/navigate-root/page-a')}>
+          Navigate Root to Page A
+        </IonButton>
+      </IonContent>
+    </IonPage>
+  );
+};

packages/react-router/test/base/tests/e2e/playwright/navigate-root.spec.ts

@@ -0,0 +1,26 @@
+import { test, expect } from '@playwright/test';
+import { ionPageVisible, ionPageDoesNotExist, withTestingMode } from './utils/test-utils';
+
+test.describe('Navigate Root', () => {
+  test('clears navigation stack and unmounts previous views', async ({ page }) => {
+    await page.goto(withTestingMode('/navigate-root/page-a'));
+    await ionPageVisible(page, 'navigate-root-page-a');
+    await expect(page.locator('#page-a-can-go-back')).toHaveText('no');
+
+    // 1. Push to page B, then page C to build up history
+    await page.locator('#go-to-page-b').click();
+    await ionPageVisible(page, 'navigate-root-page-b');
+
+    await page.locator('#go-to-page-c').click();
+    await ionPageVisible(page, 'navigate-root-page-c');
+    await expect(page.locator('#page-c-can-go-back')).toHaveText('yes');
+
+    // 2. Navigate root — should clear stack and unmount previous views
+    await page.locator('#navigate-root-to-page-a').click();
+    await ionPageVisible(page, 'navigate-root-page-a');
+    await expect(page).toHaveURL(/\/navigate-root\/page-a/);
+    await ionPageDoesNotExist(page, 'navigate-root-page-b');
+    await ionPageDoesNotExist(page, 'navigate-root-page-c');
+    await expect(page.locator('#page-a-can-go-back')).toHaveText('no');
+  });
+});

packages/react/src/components/IonRouterContext.tsx

@@ -14,6 +14,7 @@ export interface IonRouterContextState {
     animationBuilder?: AnimationBuilder
   ) => void;
   back: (animationBuilder?: AnimationBuilder) => void;
+  navigateRoot: (pathname: string, animationBuilder?: AnimationBuilder) => void;
   canGoBack: () => boolean;
   nativeBack: () => void;
 }
@@ -26,6 +27,9 @@ export const IonRouterContext = React.createContext<IonRouterContextState>({
   back: () => {
     throw new Error('An Ionic Router is required for IonRouterContext');
   },
+  navigateRoot: () => {
+    throw new Error('An Ionic Router is required for IonRouterContext');
+  },
   canGoBack: () => {
     throw new Error('An Ionic Router is required for IonRouterContext');
   },
@@ -45,10 +49,11 @@ export function useIonRouter(): UseIonRouterResult {
       back: context.back,
       push: context.push,
       goBack: context.back,
+      navigateRoot: context.navigateRoot,
       canGoBack: context.canGoBack,
       routeInfo: context.routeInfo,
     }),
-    [context.back, context.push, context.canGoBack, context.routeInfo]
+    [context.back, context.push, context.navigateRoot, context.canGoBack, context.routeInfo]
   );
 }
 
@@ -78,6 +83,13 @@ export type UseIonRouterResult = {
    * @param animationBuilder - Optional - A custom transition animation to use
    */
   goBack(animationBuilder?: AnimationBuilder): void;
+  /**
+   * Navigates to a new root pathname, clearing the navigation history and unmounting all previous views.
+   * After navigation, canGoBack() will return false. Useful for navigating to a new root after login/logout.
+   * @param pathname - The path to navigate to
+   * @param animationBuilder - Optional - A custom transition animation to use
+   */
+  navigateRoot(pathname: string, animationBuilder?: AnimationBuilder): void;
   /**
    * Determines if there are any additional routes in the Router's history. However, routing is not prevented if the browser's history has more entries. Returns true if more entries exist, false if not.
    */

packages/react/src/routing/NavManager.tsx

@@ -26,6 +26,7 @@ interface NavManagerProps {
     options?: any,
     tab?: string
   ) => void;
+  onNavigateRoot: (pathname: string, animationBuilder?: AnimationBuilder) => void;
   onSetCurrentTab: (tab: string, routeInfo: RouteInfo) => void;
   onChangeTab: (tab: string, path: string, routeOptions?: any) => void;
   onResetTab: (tab: string, path: string, routeOptions?: any) => void;
@@ -48,6 +49,9 @@ export class NavManager extends React.PureComponent<NavManagerProps, NavContextS
     back: (animationBuilder?: AnimationBuilder) => {
       this.goBack(undefined, animationBuilder);
     },
+    navigateRoot: (pathname: string, animationBuilder?: AnimationBuilder) => {
+      this.props.onNavigateRoot(pathname, animationBuilder);
+    },
     canGoBack: () => this.props.locationHistory.canGoBack(),
     nativeBack: () => this.props.onNativeBack(),
     routeInfo: this.props.routeInfo,