fix(react-router): distinguish browser forward from back in POP events

Author: ShaneK

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

@@ -82,6 +82,13 @@ export const IonRouter = ({ children, registerHistoryListener }: PropsWithChildr
   const currentTab = useRef<string | undefined>(undefined);
   const viewStack = useRef(new ReactRouterViewStack());
   const incomingRouteParams = useRef<Partial<RouteInfo> | null>(null);
+  /**
+   * Tracks URLs (pathname + search) that the user navigated away from via
+   * browser back. When a POP event's destination matches the top of this
+   * stack, it's a browser forward navigation. Cleared on PUSH (new
+   * navigation invalidates forward history, just like in the browser).
+   */
+  const forwardStack = useRef<string[]>([]);
 
   const [routeInfo, setRouteInfo] = useState<RouteInfo>({
     id: generateId('routeInfo'),
@@ -187,19 +194,31 @@ export const IonRouter = ({ children, registerHistoryListener }: PropsWithChildr
         }
         /**
          * A `POP` action can be triggered by the browser's back/forward
-         * button.
+         * button. Both fire as POP events, so we use a forward stack to
+         * distinguish them: when going back, we push the leaving pathname
+         * onto the stack. When the next POP's destination matches the top
+         * of the stack, it's a forward navigation.
          */
         if (action === 'POP') {
           const currentRoute = locationHistory.current.current();
-          /**
-           * Check if the current route was "pushed" by a previous route
-           * (indicates a linear history path).
-           */
-          if (currentRoute && currentRoute.pushedByRoute) {
+          const isForwardNavigation =
+            forwardStack.current.length > 0 &&
+            forwardStack.current[forwardStack.current.length - 1] === location.pathname + location.search;
+
+          if (isForwardNavigation) {
+            forwardStack.current.pop();
+            incomingRouteParams.current = {
+              routeAction: 'push',
+              routeDirection: 'forward',
+              tab: tabToUse,
+            };
+          } else if (currentRoute && currentRoute.pushedByRoute) {
+            // Back navigation — record current URL for potential forward
+            forwardStack.current.push(currentRoute.pathname + (currentRoute.search || ''));
             const prevInfo = locationHistory.current.findLastLocation(currentRoute);
             incomingRouteParams.current = { ...prevInfo, routeAction: 'pop', routeDirection: 'back' };
-            // It's a non-linear history path like a direct link.
           } else {
+            // It's a non-linear history path like a direct link.
             incomingRouteParams.current = {
               routeAction: 'pop',
               routeDirection: 'none',
@@ -218,6 +237,12 @@ export const IonRouter = ({ children, registerHistoryListener }: PropsWithChildr
         }
       }
 
+      // New navigation (PUSH) invalidates browser forward history,
+      // so clear our forward stack to stay in sync.
+      if (action === 'PUSH') {
+        forwardStack.current = [];
+      }
+
       let routeInfo: RouteInfo;
 
       // If we're navigating away from tabs to a non-tab route, clear the current tab
@@ -456,12 +481,17 @@ export const IonRouter = ({ children, registerHistoryListener }: PropsWithChildr
         const condition1 = routeInfo.lastPathname === routeInfo.pushedByRoute;
         const condition2 = prevInfo.pathname === routeInfo.pushedByRoute && routeInfo.tab === '' && prevInfo.tab === '';
         if (condition1 || condition2) {
+          // Record current URL so browser forward is detectable
+          forwardStack.current.push(routeInfo.pathname + (routeInfo.search || ''));
           navigate(-1);
         } else {
           /**
            * It's a non-linear back navigation.
            * e.g., direct link or tab switch or nested navigation with redirects
+           * Clear forward stack since the REPLACE-based navigate resets history
+           * position, making any prior forward entries unreachable.
            */
+          forwardStack.current = [];
           handleNavigate(prevInfo.pathname + (prevInfo.search || ''), 'pop', 'back', incomingAnimation);
         }
         /**

packages/react-router/test/base/tests/e2e/specs/nested-outlets.cy.js

@@ -117,4 +117,30 @@ describe('Nested Outlets 2', () => {
     cy.ionBackClick('list');
     cy.ionPageVisible('home');
   });
+
+  it('/nested-outlet2 > Browser back/forward across nested outlets should show correct page', () => {
+    cy.visit(`http://localhost:${port}/nested-outlet2`);
+    cy.ionPageVisible('home');
+
+    // Navigate: Home → Welcome → List → Item #1
+    cy.ionNav('ion-item', 'Go to Welcome');
+    cy.ionPageVisible('welcome');
+    cy.ionNav('ion-item', 'Go to list from Welcome');
+    cy.ionPageVisible('list');
+    cy.ionNav('ion-item', 'Item #1');
+    cy.ionPageVisible('item');
+    cy.location('pathname').should('eq', '/nested-outlet2/list/1');
+
+    // Browser back: Item → List
+    cy.go('back');
+    cy.ionPageVisible('list');
+    cy.location('pathname').should('eq', '/nested-outlet2/list');
+
+    // Browser forward: List → Item (this was showing Welcome page before the fix)
+    cy.go('forward');
+    cy.wait(500);
+    cy.ionPageVisible('item');
+    cy.location('pathname').should('eq', '/nested-outlet2/list/1');
+    cy.ionPageDoesNotExist('welcome');
+  });
 });

packages/react-router/test/base/tests/e2e/specs/routing.cy.js

@@ -204,6 +204,36 @@ describe('Routing Tests', () => {
     cy.ionPageVisible('home-page');
   });
 
+  it('/ > Details 1 > Details 2 > Details 3 > Browser Back > Browser Forward, should be back on Details 3', () => {
+    // Tests browser forward button within a tab's own navigation stack
+    cy.visit(`http://localhost:${port}/routing/`);
+    cy.ionNav('ion-item', 'Details 1');
+    cy.ionPageVisible('home-details-page-1');
+    cy.ionNav('ion-button', 'Go to Details 2');
+    cy.ionPageVisible('home-details-page-2');
+    cy.ionNav('ion-button', 'Go to Details 3');
+    cy.ionPageVisible('home-details-page-3');
+    cy.go('back');
+    cy.ionPageVisible('home-details-page-2');
+    cy.go('forward');
+    cy.wait(500);
+    cy.ionPageVisible('home-details-page-3');
+  });
+
+  it('/ > Details 1 > Settings Details 1 > Browser Back > Browser Forward, should show Settings Details 1', () => {
+    // Tests browser forward button across tabs (cross-tab forward)
+    cy.visit(`http://localhost:${port}/routing/`);
+    cy.ionNav('ion-item', 'Details 1');
+    cy.ionPageVisible('home-details-page-1');
+    cy.ionNav('ion-button', 'Go to Settings Details 1');
+    cy.ionPageVisible('settings-details-page-1');
+    cy.go('back');
+    cy.ionPageVisible('home-details-page-1');
+    cy.go('forward');
+    cy.wait(500);
+    cy.ionPageVisible('settings-details-page-1');
+  });
+
   it('when props get passed into a route render, the component should update', () => {
     cy.visit(`http://localhost:${port}/routing/propstest`);
     cy.ionPageVisible('props-test');