feat(react-router): upgrade to react router 6 #30831

ShaneK · 2025-12-02T22:23:42Z

Issue number: resolves #24177

What is the current behavior?

Currently, Ionic Framework React Router only supports React Router 5. This has many issues and unsupported/broken features.

What is the new behavior?

With this change, Ionic Framework will support React Router 6 while still supporting transitions in the same way a native app does.

Most of what caused this change to take a long time is that React Router 5 and React Router 6 have fundamental differences in how they handle components once they're no longer part of the view. In this change, we move away from relying on React Router directly so much and have our own implementation for deciding how views get dealt with during navigation and when they're cleaned up, allowing for us to still transition between them like we need to while still using React Router as much as we possibly can.

This change will also lay the foundation for the migration to React Router 7, which will ideally be easier since most of the hard work has been dealt with here.

Does this introduce a breaking change?

Yes
No

Other information

Current dev build:

⚠️ WARNING: If you're going to use this dev build on an existing react project, you'll need to migrate to React Router 6. Migrating a large project at this point might be a bad idea since this will not release until v9, which will require further migrations and have other breaking changes! I do not currently have migration documentation for this, but it's a relatively easy process from the migrations I've been doing.

8.7.13-dev.11765921002.107104c2

Co-authored-by: Sean Perkins <13732623+sean-perkins@users.noreply.github.com>

…ter 6 Co-authored-by: Sean Perkins <13732623+sean-perkins@users.noreply.github.com>

…ct router 6 Co-authored-by: Sean Perkins <13732623+sean-perkins@users.noreply.github.com>

… router 6 Co-authored-by: Sean Perkins <13732623+sean-perkins@users.noreply.github.com>

…e check

…react-router-6

thetaPC · 2025-12-08T20:46:14Z

packages/react-router/scripts/sync.sh

Would this be beneficial to add to main now?

I mean, it's a quality of life upgrade for the script. It behaves the same, it just makes it significantly more clean and uses the npm built-in commands instead of rolling our own code here. Like, it's fine to put it in main, but it's easier to just let it go to main through the v9 update.

thetaPC · 2025-12-08T20:48:55Z

packages/react-router/scripts/test_runner.sh

Was this for personal usage?

Yes, I also think it's good for everyone in the same way sync is. It does a lot of the annoying work of building and starting the server and killing the old one for you, which makes iteration much nicer. I 100% intend to commit this to main.

I'll probably create similar scripts for the other packages as we go.

thetaPC · 2025-12-08T23:16:39Z

packages/react-router/src/ReactRouter/utils/computeParentPath.ts

+ * @param options The options for computing the parent path.
+ * @returns The computed parent path result.
+ */
+export const computeParentPath = (options: ComputeParentPathOptions): ParentPathResult => {


I wonder if we can split some of the logic of computeParentPath to smaller functions so it's easier to digest the if statements.

Done! 6f184e5

.github/actions/publish-npm/action.yml

thetaPC · 2025-12-09T20:00:30Z

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

+  useEffect(() => {
+    const activeView = viewStack.current.findViewItemByRouteInfo(routeInfo, undefined, true);
+    const matchedParams = activeView?.routeData.match?.params as RouteParams | undefined;
+
+    if (matchedParams) {
+      const paramsCopy = filterUndefinedParams({ ...matchedParams });
+      if (areParamsEqual(routeInfo.params as RouteParams | undefined, paramsCopy)) {
+        return;
      }
-    } else {
-      this.handleNavigate(pathname, 'push', 'none', undefined, routeOptions, tab);
+
+      const updatedRouteInfo: RouteInfo = {
+        ...routeInfo,
+        params: paramsCopy,
+      };
+      locationHistory.current.update(updatedRouteInfo);
+      setRouteInfo(updatedRouteInfo);
    }
-  }
+  }, [routeInfo]);


Let's add a comment of what this is doing.

thetaPC · 2025-12-10T17:56:12Z

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

      <IonHeader>
        <IonToolbar>
-          <IonTitle>Main</IonTitle>
+          <IonTitle>Test App - React Router v{majorVersion}</IonTitle>


Let's make this change on main.

It doesn't seem necessary to port this to main when this is the first time we're updating the version.

I agree with Brandy, but also I don't think this change was necessary. This was very useful when I was side-by-side comparing the RR5 and RR6 test apps to see what functionality was working before vs working now, but we can never actually have multiple RR versions in the same branch, so it doesn't really make sense to keep around now. I'm just going to revert this back to saying "Main"

I think it could be useful if we ever support multiple versions at once, but yeah probably not now.

thetaPC · 2025-12-10T18:08:34Z

packages/react-router/test/base/tests/e2e/support/commands.js

  // cy.get('ion-menu.show-menu').should('exist');
  // cy.wait(1000)


Let's get rid of the commented out code.

thetaPC · 2025-12-10T18:14:32Z

packages/react/src/routing/OutletPageManager.tsx

          this.ionLifeCycleContext = context;
          return (
-            <StackManager routeInfo={routeInfo}>
+            <StackManager routeInfo={routeInfo} id={id}>


Nitpick

Suggested change

<StackManager routeInfo={routeInfo} id={id}>

<StackManager id={id} routeInfo={routeInfo}>

thetaPC · 2025-12-10T18:15:43Z

packages/react/src/routing/OutletPageManager.tsx

                setRef={(val: HTMLIonRouterOutletElement) => (this.ionRouterOutlet = val)}
+                id={id}


Nitpick

Suggested change

setRef={(val: HTMLIonRouterOutletElement) => (this.ionRouterOutlet = val)}

id={id}

id={id}

setRef={(val: HTMLIonRouterOutletElement) => (this.ionRouterOutlet = val)}

thetaPC · 2025-12-10T18:21:06Z

packages/react/test/base/scripts/sync.sh


 # Install Dependencies
-npm install *.tgz --no-save
+npm install *.tgz --no-save --legacy-peer-deps


Let's add a note of why legacy-peer-deps is needed and a TODO to remove it when possible.

…react-router-6

…o sk/react-router-6

…gation (#30854) Issue number: resolves internal ---------   ## What is the current behavior? When switching between tabs using the tab bar in a React Router 6 application, clicking IonBackButton incorrectly navigates back to the previous tab. Each tab should have its own isolated navigation history stack, and the back button should only navigate within the current tab's history. ## What is the new behavior? Tab navigation history is now properly isolated. When switching tabs via the tab bar: - The back button only navigates within the current tab's history - Pressing back on a tab root (with no navigation history) does nothing instead of navigating to the previous tab or default route - Within-tab navigation continues to work correctly (e.g., navigating to a details page and back) - Tab history is preserved when switching away and returning to a tab ## Does this introduce a breaking change? - [ ] Yes - [X] No  ## Other information  Current dev build: ``` 8.7.12-dev.11765377112.16762e5b ```

brandyscarney

Looking really good! 🚀 My comments are mostly questions & potential issues with either the test app or the router code.

brandyscarney · 2025-12-16T15:49:45Z

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

Dynamic Routes

Run the test app locally

Navigate to Dynamic Routes

Click on Take me to the newRoute

🐛 ❓ See that it navigates to a page that says New Route Failed:

Go back

Click Add Route

Click on Take me to the newRoute

🐛 See that it changes the URL but the view doesn't update

After merging all of my other RR changes into this branch (07104c2), I seem unable to replicate this. I believe this was fixed indirectly in the change that fixed changes during navigation, because it also fixed an issue with certain navigation directions. If you're able to, please pull and try this one again

BREAKING.md

brandyscarney · 2025-12-16T16:17:16Z

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

Multiple Tabs

Run the test app locally

Navigate to Multiple Tabs

Open the Menu and go to Tab 2

Click Page D

🐛 See a flicker on the menu toggle button (note: this sometimes happens going from Page A to Page B also):

route-menu-bug.mov

Refresh the page

🐛 See nothing loaded in the view

brandyscarney · 2025-12-16T16:31:20Z

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

Nested Outlet

Note
It is easier to see the transition issues in ios mode, so append ?ionic:mode=ios to the URL to switch for this test.

Run the test app locally

Navigate to Nested Outlet

Open the console

Click on Go to second page

🐛 See that there is no transition here

Click on Back with direction "back"

Click on Go to second page again

🐛 Repeat until you see a log when clicking Go to second page without navigation, see video below

nested-outlet-bug.mov

brandyscarney · 2025-12-16T19:54:41Z

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

      <IonHeader>
        <IonToolbar>
-          <IonTitle>Main</IonTitle>
+          <IonTitle>Test App - React Router v{majorVersion}</IonTitle>


It doesn't seem necessary to port this to main when this is the first time we're updating the version.

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

brandyscarney · 2025-12-16T20:13:34Z

packages/react-router/scripts/sync.sh

What was the reason for this update?

This is a massive QoL improvement for this file, we go from rolling our own sync to using npm's integrated sync. This should make maintaining this file a lot easier and it's generally less fragile.

Okay I am just worried about it getting out of sync somehow. 😂 We should make a task to update the others the same way if it works the same.

packages/react-router/src/ReactRouter/utils/computeParentPath.ts

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

…RouterOutlet (#30844) Issue number: resolves [an issue from a comment](#24177 (comment)) --------- ## What is the current behavior?  Currently, Ionic's RR6 doesn't support relative routes in the same way RR6 does. Routes that do not start with a `/`do not work in the Ionic RR6 implementation in some cases. ## What is the new behavior? With this change, we properly support these route styles and more closely align with normal RR6 route support. ## Does this introduce a breaking change? - [ ] Yes - [X] No  ## Other information Current dev build: ``` 8.7.12-dev.11765307927.1f491e92 ``` This PR will be merged into the RR6 branch, which will be squash+merged into the major 9 branch. This will prevent major 9 from having commits in the change log on release that reference fixing things that are only available in major 9.

…p, and a bit of ordering

…ation

thetaPC and others added 30 commits May 8, 2025 14:49

chore(deps): update react router to v6

4262324

refactor(utils): update matchPath for rr6

f0127bd

refactor(reactrouterviewstack): update for rr6 and improvements

cccf290

refactor(test): updated test pages

af7710b

chore(matchPath): use the correct library

e364fea

chore(rr6): run lint

6a42e69

chore(StackManager): upgrade to rr6 and add comments

4aad76a

chore(StackManager): more upgrades for rr6

fd6baac

docs(StackManager): update comment

e76c1e8

docs(matchPath): remove comment

2436ba3

chore(IonRouteInner): upgrade to rr6

ca27ed6

chore(StackManager): run lint

37f76c7

feat(IonRouter): migrate to functional component with react router 6

a78f6b3

Co-authored-by: Sean Perkins <13732623+sean-perkins@users.noreply.github.com>

chore(IonRouteInner): update render

93202c0

docs(IonRouter, ReactRouterViewStack, StackManager): update comments

0008059

feat(IonReactRouter): migrate to a functional component and react rou…

0a0dcb6

…ter 6 Co-authored-by: Sean Perkins <13732623+sean-perkins@users.noreply.github.com>

feat(IonReactMemoryRouter): migrate to a functional component and rea…

331b394

…ct router 6 Co-authored-by: Sean Perkins <13732623+sean-perkins@users.noreply.github.com>

chore(IonReactMemoryRouter): remove unused type

205a705

feat(IonReactHashRouter): migrate to a functional component and react…

7ff8994

… router 6 Co-authored-by: Sean Perkins <13732623+sean-perkins@users.noreply.github.com>

docs(many): update comments

c45c0f9

refactor(many): remove exact from test pages

12c49f5

refactor(many): update to use <Navigate>

71fb8cb

refactor(many): replace render with element

c6f8dd4

refactor(Tabs2): switch to navigate

366004e

refactor(many): update to prevent compile errors

5cccf0b

refactor(IonReactRouter): split component to use hooks correctly

e6e17eb

chore: update package and sync file

2656e98

docs(IonReactRouter): use updated param names

10bb889

fix(ReactRouterViewStack, StackManager): use correct value & add valu…

7a20697

…e check

Merge branch 'main' of github.com:ionic-team/ionic-framework into mh/…

9d69a69

…react-router-6

thetaPC reviewed Dec 10, 2025

View reviewed changes

ShaneK added 2 commits December 10, 2025 13:07

Merge branch 'main' of github.com:ionic-team/ionic-framework into sk/…

b196665

…react-router-6

Merge branch 'major-9.0' of github.com:ionic-team/ionic-framework int…

2ff49c4

…o sk/react-router-6

github-actions bot removed the package: core @ionic/core package label Dec 10, 2025

vercel bot deployed to Preview December 10, 2025 21:19 View deployment

vercel bot deployed to Preview December 10, 2025 21:52 View deployment

vercel bot deployed to Preview December 10, 2025 23:02 View deployment

ShaneK force-pushed the sk/react-router-6 branch from 8104d09 to 6f3bba7 Compare December 10, 2025 23:50

vercel bot deployed to Preview December 10, 2025 23:51 View deployment

ShaneK force-pushed the sk/react-router-6 branch from 6f3bba7 to 0c82ee2 Compare December 10, 2025 23:57

vercel bot deployed to Preview December 10, 2025 23:58 View deployment

chore(git): merge conflict resolution

6a61ecf

ShaneK force-pushed the sk/react-router-6 branch from 0c82ee2 to 6a61ecf Compare December 11, 2025 00:06

vercel bot deployed to Preview December 11, 2025 00:07 View deployment

brandyscarney self-requested a review December 11, 2025 18:40

brandyscarney reviewed Dec 16, 2025

View reviewed changes

vercel bot deployed to Preview December 16, 2025 21:33 View deployment

ShaneK added 4 commits December 17, 2025 09:10

fix(react-router): moving view stack back to generate ID

e1e7a2e

chore(react-router): lots of comments, code clean up, comment clean u…

d0451ed

…p, and a bit of ordering

refactor(react-router): extract helper functions from computeParentPath

6f184e5

refactor(react-router): extract helper functions from render callback

d44fc11

vercel bot deployed to Preview December 17, 2025 18:26 View deployment

chore(react-router): documentation, comment clean up, and more

289f6ed

vercel bot deployed to Preview December 17, 2025 19:22 View deployment

vercel bot deployed to Preview December 17, 2025 20:03 View deployment

fix(react-router): cleanup orphaned sibling views after replace navig…

ab3dde2

…ation

ShaneK force-pushed the sk/react-router-6 branch from 2929474 to ab3dde2 Compare December 17, 2025 20:04

vercel bot deployed to Preview December 17, 2025 20:05 View deployment

		// cy.get('ion-menu.show-menu').should('exist');
		// cy.wait(1000)

	<StackManager routeInfo={routeInfo} id={id}>
	<StackManager id={id} routeInfo={routeInfo}>

		setRef={(val: HTMLIonRouterOutletElement) => (this.ionRouterOutlet = val)}
		id={id}

feat(react-router): upgrade to react router 6 #30831

Are you sure you want to change the base?

feat(react-router): upgrade to react router 6 #30831

Uh oh!

Conversation

ShaneK commented Dec 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What is the current behavior?

What is the new behavior?

Does this introduce a breaking change?

Other information

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ShaneK Dec 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ShaneK Dec 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

brandyscarney left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Dynamic Routes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Multiple Tabs

Uh oh!

Choose a reason for hiding this comment

Nested Outlet

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ShaneK commented Dec 2, 2025 •

edited

Loading

ShaneK Dec 10, 2025 •

edited

Loading

ShaneK Dec 17, 2025 •

edited

Loading