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

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

mhartington · 2025-12-03T14:22:27Z

Took you long enough...Good job shane

docs/react-router/react-router-6-status.md

brandyscarney · 2025-12-03T14:34:33Z

.github/workflows/stencil-nightly.yml

      fail-fast: false
      matrix:
-        apps: [reactrouter5]
+        apps: [reactrouter6]


We should either update the breaking changes file to include no longer supporting react router 5 or create a follow-up task since doing so might conflict with next: https://github.com/ionic-team/ionic-framework/blob/next/BREAKING.md

Yeah, I still need to document migration strategies and such. For the most part, it's a pretty easy migration (ignore the inline overlay stuff, that was all removed), but I just need to write it out.

I went ahead and did this in this branch, figuring it would be an easy enough merge conflict resolution. If you'd like to review in an easier to read way:
https://github.com/ionic-team/ionic-framework/blob/b2a71050344052a4858d0c8b6712f0d5bc9d7219/BREAKING.md

It looks good but the v8 breaking changes need to be moved to here: https://github.com/ionic-team/ionic-framework/tree/b2a71050344052a4858d0c8b6712f0d5bc9d7219/BREAKING_ARCHIVE

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

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

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

ShaneK requested review from brandyscarney and thetaPC December 3, 2025 14:20

brandyscarney reviewed Dec 3, 2025

View reviewed changes

docs/react-router/react-router-6-status.md Outdated Show resolved Hide resolved

brandyscarney reviewed Dec 3, 2025

View reviewed changes

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

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

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!

mhartington commented Dec 3, 2025

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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

ShaneK commented Dec 2, 2025 •

edited

Loading

ShaneK Dec 10, 2025 •

edited

Loading