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 <[email protected]>

…ter 6 Co-authored-by: Sean Perkins <[email protected]>

…ct router 6 Co-authored-by: Sean Perkins <[email protected]>

… router 6 Co-authored-by: Sean Perkins <[email protected]>

…e check

…react-router-6

.github/workflows/stencil-nightly.yml

…een sibling routes

…react-router-6

…gation

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

packages/react-router/scripts/sync.sh

Would this be beneficial to add to main now?

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.

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

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

brandyscarney · 2025-12-16T15:57:40Z

BREAKING.md

+
+For more information on migrating from React Router v5 to v6, refer to the [React Router v6 Upgrade Guide](https://reactrouter.com/en/main/upgrading/v5).
+
 ## Version 8.x


Version 8 needs to be moved to its own file, see the next branch: https://github.com/ionic-team/ionic-framework/blob/next/BREAKING_ARCHIVE/v8.md

brandyscarney · 2025-12-16T15:59:12Z

BREAKING.md

+
+<h2 id="version-9x-framework-specific">Framework Specific</h2>
+
+<h4 id="version-9x-react">React</h4>


Should this be React Router?

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.

brandyscarney · 2025-12-16T20:10:46Z

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

    cy.ionMenuNav('Home with redirect');
    cy.ionPageVisible('home-page');
-    cy.ionPageDoesNotExist('favorites-page');
+    cy.ionPageHidden('favorites-page');


Why was this change needed?

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

packages/react-router/scripts/sync.sh

What was the reason for this update?

brandyscarney · 2025-12-16T20:24:46Z

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

+      let firstSpecificMatch: string | undefined = undefined;
+      let firstWildcardMatch: string | undefined = undefined;
+      let indexMatchAtMount: string | undefined = undefined;


Suggested change

let firstSpecificMatch: string | undefined = undefined;

let firstWildcardMatch: string | undefined = undefined;

let indexMatchAtMount: string | undefined = undefined;

let firstSpecificMatch: string | undefined;

let firstWildcardMatch: string | undefined;

let indexMatchAtMount: string | undefined;

brandyscarney · 2025-12-16T20:36:49Z

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

+          lastPathname: leavingLocationInfo.pathname, // The URL we just came from
+          pathname: location.pathname, // The current (destination) URL


Should we change this to something like prevPathname and nextPathname to make it more obvious?

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

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 <[email protected]>

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 <[email protected]>

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

331b394

…ct router 6 Co-authored-by: Sean Perkins <[email protected]>

chore(IonReactMemoryRouter): remove unused type

205a705

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

7ff8994

… router 6 Co-authored-by: Sean Perkins <[email protected]>

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

brandyscarney reviewed Dec 3, 2025

View reviewed changes

.github/workflows/stencil-nightly.yml Show resolved Hide resolved

ShaneK mentioned this pull request Dec 3, 2025

feat: React Router v6 support #24177

Open

3 tasks

ShaneK added 2 commits December 4, 2025 06:03

chore(docs): removing status doc link

cb94f73

fix(react-router): preserve nested outlet params when navigating betw…

fedca46

…een sibling routes

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

chore(react-router): adding migration details to BREAKING.md

b2a7105

vercel bot deployed to Preview December 4, 2025 19:59 View deployment

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

7fc43b6

…react-router-6

github-actions bot added the package: core @ionic/core package label Dec 9, 2025

vercel bot deployed to Preview December 9, 2025 17:14 View deployment

fix(react-router): isolate tab history to prevent cross-tab back navi…

6762e5b

…gation

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

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


		For more information on migrating from React Router v5 to v6, refer to the [React Router v6 Upgrade Guide](https://reactrouter.com/en/main/upgrading/v5).

		## Version 8.x


		<h2 id="version-9x-framework-specific">Framework Specific</h2>

		<h4 id="version-9x-react">React</h4>

		lastPathname: leavingLocationInfo.pathname, // The URL we just came from
		pathname: location.pathname, // The current (destination) URL

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

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!

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!

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!

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

Multiple Tabs

Uh oh!

Choose a reason for hiding this comment

Nested Outlet

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

ShaneK commented Dec 2, 2025 •

edited

Loading

ShaneK Dec 10, 2025 •

edited

Loading