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

Issue number: resolves #24177

---------

<!-- Please do not submit updates to dependencies unless it fixes an
issue. -->

<!-- Please try to limit your pull request to one type (bugfix, feature,
etc). Submit multiple pull requests if needed. -->

## 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?

- [X] Yes
- [ ] No

<!--
  If this introduces a breaking change:
1. Describe the impact and migration path for existing applications
below.
  2. Update the BREAKING.md file with the breaking change.
3. Add "BREAKING CHANGE: [...]" to the commit description when merging.
See
https://github.com/ionic-team/ionic-framework/blob/main/docs/CONTRIBUTING.md#footer
for more information.
-->


## Other information

<!-- Any other information that is important to this PR such as
screenshots of how the component looks before and after the change. -->

Current dev build (last updated 2026-04-27):

> **⚠️ 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 have a preview of migration documentation for this
[here](https://ionic-docs-git-v9-react-router-ionic1.vercel.app/docs/updating/9-0#react-router).

```
8.8.4-dev.11777318673.18d001f6
```

The dev build linked above will be the last one for this branch alone.
Everything going forward will be the major-9.0 branch, which may include
large breaking changes.

---------

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

Author: 3 people

.github/workflows/actions/test-react-router-e2e/action.yml

@@ -29,7 +29,11 @@ runs:
       shell: bash
       working-directory: ./packages/react-router/test
     - name: 🕸️ Install Dependencies
-      run: npm install
+      run: npm install --legacy-peer-deps
+      shell: bash
+      working-directory: ./packages/react-router/test/build/${{ inputs.app }}
+    - name: 📦 Install Playwright Browsers
+      run: npx playwright install chromium
       shell: bash
       working-directory: ./packages/react-router/test/build/${{ inputs.app }}
     - name: 🔄 Sync Built Changes
@@ -40,7 +44,13 @@ runs:
       run: npm run build
       shell: bash
       working-directory: ./packages/react-router/test/build/${{ inputs.app }}
-    - name: 🧪 Run Tests
+    - name: 🧪 Run Cypress Tests
       run: npm run e2e
       shell: bash
       working-directory: ./packages/react-router/test/build/${{ inputs.app }}
+    - name: 🎭 Run Playwright Tests
+      run: npx playwright test --retries=2
+      env:
+        CI: true
+      shell: bash
+      working-directory: ./packages/react-router/test/build/${{ inputs.app }}

.github/workflows/build.yml

@@ -176,7 +176,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        apps: [reactrouter5]
+        apps: [reactrouter6-react18, reactrouter6-react19]
     needs: [build-react, build-react-router]
     runs-on: ubuntu-latest
     steps:

.github/workflows/stencil-nightly.yml

@@ -186,7 +186,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        apps: [reactrouter5]
+        apps: [reactrouter6-react18, reactrouter6-react19]
     needs: [build-react, build-react-router]
     runs-on: ubuntu-latest
     steps:

BREAKING.md

@@ -18,6 +18,8 @@ This is a comprehensive list of the breaking changes introduced in the major ver
 - [Components](#version-9x-components)
   - [Legacy Picker](#version-9x-legacy-picker)
   - [Router Outlet](#version-9x-router-outlet)
+- [Framework Specific](#version-9x-framework-specific)
+  - [React](#version-9x-react)
 
 <h2 id="version-9x-browser-platform-support">Browser and Platform Support</h2>
 
@@ -68,3 +70,184 @@ To disable the gesture on a specific outlet, set `swipeGesture` to `false`:
 ```
 
 The `swipeBackEnabled` config option is still respected as the initial default and does not need to change for apps that set it once at startup.
+
+<h2 id="version-9x-framework-specific">Framework Specific</h2>
+
+<h4 id="version-9x-react">React</h4>
+
+The `@ionic/react-router` package now requires React Router v6. React Router v5 is no longer supported.
+
+**Minimum Version Requirements**
+| Package | Supported Version |
+| ---------------- | ----------------- |
+| react-router     | 6.0.0+            |
+| react-router-dom | 6.0.0+            |
+
+React Router v6 introduces several API changes that will require updates to your application's routing configuration:
+
+**Route Definition Changes**
+
+The `component` prop has been replaced with the `element` prop, which accepts JSX:
+
+```diff
+- <Route path="/home" component={Home} exact />
++ <Route path="/home" element={<Home />} />
+```
+
+**Redirect Changes**
+
+The `<Redirect>` component has been replaced with `<Navigate>`:
+
+```diff
+- import { Redirect } from 'react-router-dom';
++ import { Navigate } from 'react-router-dom';
+
+- <Redirect to="/home" />
++ <Navigate to="/home" replace />
+```
+
+**Nested Route Paths**
+
+Routes that contain nested routes or child `IonRouterOutlet` components need a `/*` suffix to match sub-paths:
+
+```diff
+- <Route path="/tabs" element={<Tabs />} />
++ <Route path="/tabs/*" element={<Tabs />} />
+```
+
+**Accessing Route Parameters**
+
+Route parameters are now accessed via the `useParams` hook instead of props:
+
+```diff
+- import { RouteComponentProps } from 'react-router-dom';
++ import { useParams } from 'react-router-dom';
+
+- const MyComponent: React.FC<RouteComponentProps<{ id: string }>> = ({ match }) => {
+-   const id = match.params.id;
++ const MyComponent: React.FC = () => {
++   const { id } = useParams<{ id: string }>();
+```
+
+**RouteComponentProps Removed**
+
+The `RouteComponentProps` type and its `history`, `location`, and `match` props are no longer available in React Router v6. Use the equivalent hooks instead:
+
+- `history` -> `useNavigate` (see below) or `useIonRouter`
+- `match.params` -> `useParams` (covered above)
+- `location` -> `useLocation`
+
+```diff
+- import { RouteComponentProps } from 'react-router-dom';
++ import { useNavigate, useLocation } from 'react-router-dom';
++ import { useIonRouter } from '@ionic/react';
+
+- const MyComponent: React.FC<RouteComponentProps> = ({ history, location }) => {
+-   history.push('/path');
+-   history.replace('/path');
+-   history.goBack();
+-   console.log(location.pathname);
++ const MyComponent: React.FC = () => {
++   const navigate = useNavigate();
++   const router = useIonRouter();
++   const location = useLocation();
++   // In an event handler or useEffect:
++   navigate('/path');
++   navigate('/path', { replace: true });
++   router.goBack();
++   console.log(location.pathname);
+```
+
+**Exact Prop Removed**
+
+The `exact` prop is no longer needed. React Router v6 routes match exactly by default. To match sub-paths, use a `/*` suffix on the path:
+
+```diff
+- <Route path="/home" exact />
++ <Route path="/home" />
+```
+
+**Render Prop Removed**
+
+The `render` prop has been replaced with the `element` prop:
+
+```diff
+- <Route path="/foo" render={(props) => <Foo {...props} />} />
++ <Route path="/foo" element={<Foo />} />
+```
+
+**Programmatic Navigation**
+
+The `useHistory` hook has been replaced with `useNavigate`:
+
+```diff
+- import { useHistory } from 'react-router-dom';
++ import { useNavigate } from 'react-router-dom';
++ import { useIonRouter } from '@ionic/react';
+
+- const history = useHistory();
++ const navigate = useNavigate();
++ const router = useIonRouter();
+
+- history.push('/path');
++ navigate('/path');
+
+- history.replace('/path');
++ navigate('/path', { replace: true });
+
+- history.goBack();
++ router.goBack();
+```
+
+**Custom History Prop Removed**
+
+The `history` prop has been removed from `IonReactRouter`, `IonReactHashRouter`, and `IonReactMemoryRouter`. React Router v6's `BrowserRouter`, `HashRouter`, and `MemoryRouter` no longer accept custom `history` objects.
+
+```diff
+- import { createBrowserHistory } from 'history';
+- const history = createBrowserHistory();
+- <IonReactRouter history={history}>
++ <IonReactRouter>
+```
+
+For `IonReactMemoryRouter` (commonly used in tests), use `initialEntries` instead:
+
+```diff
+- import { createMemoryHistory } from 'history';
+- const history = createMemoryHistory({ initialEntries: ['/start'] });
+- <IonReactMemoryRouter history={history}>
++ <IonReactMemoryRouter initialEntries={['/start']}>
+```
+
+**IonRedirect Removed**
+
+The `IonRedirect` component has been removed. Use React Router's `<Navigate>` component instead:
+
+```diff
+- import { IonRedirect } from '@ionic/react';
+- <IonRedirect path="/old" to="/new" exact />
++ import { Navigate } from 'react-router-dom';
++ <Route path="/old" element={<Navigate to="/new" replace />} />
+```
+
+**Path Regex Constraints Removed**
+
+React Router v6 no longer supports regex constraints in path parameters (e.g., `/:tab(sessions)`). Use literal paths instead:
+
+```diff
+- <Route path="/:tab(sessions)" component={SessionsPage} />
+- <Route path="/:tab(sessions)/:id" component={SessionDetail} />
++ <Route path="/sessions" element={<SessionsPage />} />
++ <Route path="/sessions/:id" element={<SessionDetail />} />
+```
+
+**IonRoute API Changes**
+
+The `IonRoute` component follows the same API changes as React Router's `<Route>`. The `render` prop has been replaced with `element`, and the `exact` prop has been removed:
+
+```diff
+- <IonRoute path="/foo" exact render={(props) => <Foo {...props} />} />
++ <IonRoute path="/foo" element={<Foo />} />
+```
+
+For more information on migrating from React Router v5 to v6, refer to the [React Router v6 Upgrade Guide](https://reactrouter.com/6.28.0/upgrading/v5).