docs(react-router): updating docs to reflect react router 6 changes (#4422)

* docs(react-router): working on v9 migration docs for react router

* docs(react-router): update navigation guide and expand v5-to-v6 migration guide

* chore(lint): running lint

* fix(build): fixing build error

* docs(react-router): fixing several issues

* docs(react-router): converting playground example to rr6

* docs(react-router): updating dependencies, reverting phrasing change

Author: ShaneK

.prettierignore

@@ -8,6 +8,7 @@ docs/native
 versioned_docs/version-v*/native
 docs/cli/commands
 docs/reference/glossary.md
+versioned_docs/version-v*/reference/glossary.md
 
 static/code/stackblitz
 

docs/react/add-to-existing.md

@@ -302,21 +302,20 @@ Then, create `src/pages/Home.css`:
 
 :::important
 
-Ionic React Router currently only supports React Router v5. You must install the following specific versions of the router packages to set up routing with Ionic React.
+Ionic React requires React Router v6. Install the following specific versions of the router packages to set up routing with Ionic React.
 
 :::
 
 Install the router packages:
 
 ```bash
-npm install @ionic/react-router react-router@5 react-router-dom@5
-npm install @types/react-router-dom --save-dev
+npm install @ionic/react-router react-router@6 react-router-dom@6
 ```
 
 Then, update `src/App.tsx` to add the routes for the Home page:
 
 ```tsx title="src/App.tsx"
-import { Redirect, Route } from 'react-router-dom';
+import { Route, Navigate } from 'react-router-dom';
 import { IonApp, IonRouterOutlet, setupIonicReact } from '@ionic/react';
 import { IonReactRouter } from '@ionic/react-router';
 import Home from './pages/Home';
@@ -329,12 +328,8 @@ const App: React.FC = () => (
   <IonApp>
     <IonReactRouter>
       <IonRouterOutlet>
-        <Route exact path="/home">
-          <Home />
-        </Route>
-        <Route exact path="/">
-          <Redirect to="/home" />
-        </Route>
+        <Route path="/home" element={<Home />} />
+        <Route path="/" element={<Navigate to="/home" replace />} />
       </IonRouterOutlet>
     </IonReactRouter>
   </IonApp>

docs/react/navigation.md

@@ -78,7 +78,7 @@ Let's walk through these files to understand the app's structure.
 The root of your app is defined in `App.tsx`:
 
 ```tsx title="src/App.tsx"
-import { Redirect, Route } from 'react-router-dom';
+import { Route, Navigate } from 'react-router-dom';
 import { IonApp, IonRouterOutlet, setupIonicReact } from '@ionic/react';
 import { IonReactRouter } from '@ionic/react-router';
 import Home from './pages/Home';
@@ -91,12 +91,8 @@ const App: React.FC = () => (
   <IonApp>
     <IonReactRouter>
       <IonRouterOutlet>
-        <Route exact path="/home">
-          <Home />
-        </Route>
-        <Route exact path="/">
-          <Redirect to="/home" />
-        </Route>
+        <Route path="/home" element={<Home />} />
+        <Route path="/" element={<Navigate to="/home" replace />} />
       </IonRouterOutlet>
     </IonReactRouter>
   </IonApp>
@@ -113,12 +109,8 @@ Routes are defined within the `IonRouterOutlet` in `App.tsx`:
 
 ```tsx title="src/App.tsx"
 <IonRouterOutlet>
-  <Route exact path="/home">
-    <Home />
-  </Route>
-  <Route exact path="/">
-    <Redirect to="/home" />
-  </Route>
+  <Route path="/home" element={<Home />} />
+  <Route path="/" element={<Navigate to="/home" replace />} />
 </IonRouterOutlet>
 ```
 
@@ -240,15 +232,9 @@ Then, add its route in `IonRouterOutlet`:
 
 ```tsx title="src/App.tsx"
 <IonRouterOutlet>
-  <Route exact path="/home">
-    <Home />
-  </Route>
-  <Route exact path="/new">
-    <New />
-  </Route>
-  <Route exact path="/">
-    <Redirect to="/home" />
-  </Route>
+  <Route path="/home" element={<Home />} />
+  <Route path="/new" element={<New />} />
+  <Route path="/" element={<Navigate to="/home" replace />} />
 </IonRouterOutlet>
 ```
 
@@ -259,7 +245,7 @@ Once that is done, update the button in `Home.tsx`:
 ```
 
 :::info
-Navigating can also be performed programmatically using React Router's `history` prop. See the [React Navigation documentation](/docs/react/navigation.md#navigating-using-history) for more information.
+Navigating can also be performed programmatically using the `useIonRouter` hook. See the [React Navigation documentation](/docs/react/navigation.md#useionrouter) for more information.
 :::
 
 ## Add Icons to the New Page

docs/react/quickstart.md

@@ -234,7 +234,7 @@ export default Tab2;
 Next, open `src/App.tsx`. Change the label to "Photos" and the `ellipse` icon to `images` for the middle tab button.
 
 ```tsx
-import { Redirect, Route } from 'react-router-dom';
+import { Route, Navigate } from 'react-router-dom';
 import {
   IonApp,
   IonIcon,
@@ -259,18 +259,10 @@ const App: React.FC = () => (
     <IonReactRouter>
       <IonTabs>
         <IonRouterOutlet>
-          <Route exact path="/tab1">
-            <Tab1 />
-          </Route>
-          <Route exact path="/tab2">
-            <Tab2 />
-          </Route>
-          <Route path="/tab3">
-            <Tab3 />
-          </Route>
-          <Route exact path="/">
-            <Redirect to="/tab1" />
-          </Route>
+          <Route path="/tab1" element={<Tab1 />} />
+          <Route path="/tab2" element={<Tab2 />} />
+          <Route path="/tab3" element={<Tab3 />} />
+          <Route path="/" element={<Navigate to="/tab1" replace />} />
         </IonRouterOutlet>
         <IonTabBar slot="bottom">
           <IonTabButton tab="tab1" href="/tab1">

docs/react/your-first-app.md

@@ -44,6 +44,198 @@ npm install react@latest react-dom@latest
 npm install @ionic/react@latest @ionic/react-router@latest
 ```
 
+### React Router
+
+1. Ionic 9 supports React Router 6. Update to version 6 of React Router:
+
+```shell
+npm install react-router@6 react-router-dom@6
+```
+
+2. If you have `@types/react-router` or `@types/react-router-dom` installed, remove them. React Router 6 includes its own TypeScript definitions:
+
+```shell
+npm uninstall @types/react-router @types/react-router-dom
+```
+
+Ionic React now requires React Router v6, which has a different API from v5. Below are the key changes you'll need to make.
+
+#### Route Definition Changes
+
+The `component` and `render` props have been replaced with the `element` prop, which accepts JSX:
+
+```diff
+- <Route path="/home" component={Home} exact />
++ <Route path="/home" element={<Home />} />
+```
+
+Routes can no longer render content via nested children. All route content must be passed through the `element` prop:
+
+```diff
+- <Route path="/">
+-   <Home />
+- </Route>
++ <Route path="/" 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 routers 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).
+
 ### Vue
 
 1. Ionic 9 supports Vue 3.0.6+. Update to the latest version of Vue:
@@ -65,3 +257,9 @@ npm install @ionic/vue@latest @ionic/vue-router@latest
 ```shell
 npm install @ionic/core@latest
 ```
+
+## Need Help Upgrading?
+
+Be sure to look at the [Ionic 9 Breaking Changes Guide](https://github.com/ionic-team/ionic-framework/blob/main/BREAKING.md#version-9x) for the complete list of breaking changes. This upgrade guide only covers changes that require action from developers.
+
+If you need help upgrading, please post a thread on the [Ionic Forum](https://forum.ionicframework.com/).

docs/updating/9-0.md

@@ -8,14 +8,12 @@
     "@types/node": "^24.0.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
-    "@types/react-router": "^5.1.11",
-    "@types/react-router-dom": "^5.1.7",
     "@vitejs/plugin-react": "^5.0.0",
     "clsx": "^2.0.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "react-router": "^5.2.0",
-    "react-router-dom": "^5.2.0",
+    "react-router": "^6.0.0",
+    "react-router-dom": "^6.0.0",
     "typescript": "~5.9.0",
     "vite": "^7.0.0",
     "web-vitals": "^5.0.0"