Skip to content

Commit 7c3ecd9

Browse files
ShaneKShaneK
committed
Merge branch 'major-9.0' of github.com:ionic-team/ionic-docs into v9/item-routing
2 parents 1ed632b + fbf2799 commit 7c3ecd9

23 files changed

+664
-109
lines changed

‎docs/angular/navigation.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -201,7 +201,9 @@ To get started with standalone components [visit Angular's official docs](https:
201201

202202
## Live Example
203203

204-
If you would prefer to get hands on with the concepts and code described above, please checkout our [live example](https://stackblitz.com/edit/ionic-angular-routing?file=src/app/app-routing.module.ts) of the topics above on StackBlitz.
204+
import NavigationPlayground from '@site/static/usage/v9/navigation/index.md';
205+
206+
<NavigationPlayground defaultFramework="angular" />
205207

206208
## Linear Routing versus Non-Linear Routing
207209

‎docs/react/navigation.md‎

Lines changed: 40 additions & 103 deletions
Original file line numberDiff line numberDiff line change
@@ -57,31 +57,31 @@ Inside the Dashboard page, we define more routes related to this specific sectio
5757
**DashboardPage.tsx**
5858

5959
```tsx
60-
const DashboardPage: React.FC = () => {
61-
return (
62-
<IonPage>
63-
<IonRouterOutlet>
64-
<Route index element={<UsersListPage />} />
65-
<Route path="users/:id" element={<UserDetailPage />} />
66-
</IonRouterOutlet>
67-
</IonPage>
68-
);
69-
};
60+
const DashboardPage: React.FC = () => (
61+
<IonRouterOutlet ionPage>
62+
<Route index element={<UsersListPage />} />
63+
<Route path="users/:id" element={<UserDetailPage />} />
64+
</IonRouterOutlet>
65+
);
7066
```
7167

7268
Since the parent route already matches `/dashboard/*`, the child routes use **relative paths**. The `index` route matches the parent path (`/dashboard`) and `"users/:id"` resolves to `/dashboard/users/:id`. Absolute paths (e.g., `path="/dashboard/users/:id"`) still work if you prefer explicit full paths.
7369

70+
Note the `ionPage` prop on `IonRouterOutlet`. When a component serves as a nested outlet rendered directly by a `Route` in a parent outlet, the inner `IonRouterOutlet` must include the `ionPage` prop. Without it, router outlets can overlap during navigation and cause broken transitions. Wrapping the outlet in an `IonPage` is not needed and should be avoided in this case.
71+
7472
These routes are grouped in an `IonRouterOutlet`, let's discuss that next.
7573

76-
## IonRouterOutlet
74+
## Components
75+
76+
### IonRouterOutlet
7777

7878
The `IonRouterOutlet` component provides a container for Routes that render Ionic "pages". When a page is in an `IonRouterOutlet`, the container controls the transition animation between the pages as well as controls when a page is created and destroyed, which helps maintain the state between the views when switching back and forth between them.
7979

8080
The `DashboardPage` above shows a users list page and a details page. When navigating between the two pages, the `IonRouterOutlet` provides the appropriate platform page transition and keeps the state of the previous page intact so that when a user navigates back to the list page, it appears in the same state as when it left.
8181

8282
An `IonRouterOutlet` should only contain `Route`s. Any other component should be rendered either as a result of a `Route` or outside of the `IonRouterOutlet`.
8383

84-
## Fallback Route
84+
### Fallback Route
8585

8686
A common routing use case is to provide a "fallback" route to be rendered in the event the location navigated to does not match any of the routes defined.
8787

@@ -90,38 +90,30 @@ We can define a fallback route by placing a `Route` component with a `path` of `
9090
**DashboardPage.tsx**
9191

9292
```tsx
93-
const DashboardPage: React.FC = () => {
94-
return (
95-
<IonPage>
96-
<IonRouterOutlet>
97-
<Route index element={<UsersListPage />} />
98-
<Route path="users/:id" element={<UserDetailPage />} />
99-
<Route path="*" element={<Navigate to="/dashboard" replace />} />
100-
</IonRouterOutlet>
101-
</IonPage>
102-
);
103-
};
93+
const DashboardPage: React.FC = () => (
94+
<IonRouterOutlet ionPage>
95+
<Route index element={<UsersListPage />} />
96+
<Route path="users/:id" element={<UserDetailPage />} />
97+
<Route path="*" element={<Navigate to="/dashboard" replace />} />
98+
</IonRouterOutlet>
99+
);
104100
```
105101

106102
Here, we see that in the event a location does not match the first two `Route`s the `IonRouterOutlet` will redirect the Ionic React app to the `/dashboard` path.
107103

108104
You can alternatively supply a component to render instead of providing a redirect.
109105

110106
```tsx
111-
const DashboardPage: React.FC = () => {
112-
return (
113-
<IonPage>
114-
<IonRouterOutlet>
115-
<Route index element={<UsersListPage />} />
116-
<Route path="users/:id" element={<UserDetailPage />} />
117-
<Route path="*" element={<NotFoundPage />} />
118-
</IonRouterOutlet>
119-
</IonPage>
120-
);
121-
};
107+
const DashboardPage: React.FC = () => (
108+
<IonRouterOutlet ionPage>
109+
<Route index element={<UsersListPage />} />
110+
<Route path="users/:id" element={<UserDetailPage />} />
111+
<Route path="*" element={<NotFoundPage />} />
112+
</IonRouterOutlet>
113+
);
122114
```
123115

124-
## IonPage
116+
### IonPage
125117

126118
The `IonPage` component wraps each view in an Ionic React app and allows page transitions and stack navigation to work properly. Each view that is navigated to using the router must include an `IonPage` component.
127119

@@ -186,7 +178,7 @@ Outside of these components that have the `routerLink` prop, you can also use Re
186178

187179
We recommend using one of the above methods whenever possible for routing. The advantage to these approaches is that they both render an anchor (`<a>`)tag, which is suitable for overall app accessibility.
188180

189-
For programmatic navigation, use the `useIonRouter` hook (see [Utilities](#useionrouter)) or React Router's [`useNavigate`](https://reactrouter.com/6.28.0/hooks/use-navigate) hook:
181+
For programmatic navigation, use the `useIonRouter` hook (review [Utility Functions](./utility-functions.md#useionrouter)) or React Router's [`useNavigate`](https://reactrouter.com/6.28.0/hooks/use-navigate) hook:
190182

191183
```tsx
192184
import { useNavigate } from 'react-router-dom';
@@ -217,7 +209,7 @@ Say you have the following application history:
217209

218210
If you were to call `navigate(-2)` on `/pageC`, you would be brought back to `/pageA`. If you then called `navigate(2)`, you would be brought to `/pageC`.
219211

220-
Using `navigate()` with delta values is not recommended in Ionic React because it follows the browser's linear history, which does not account for Ionic's non-linear tab and nested outlet navigation stacks. Use the `useIonRouter` hook's [`goBack()`](#useionrouter) method instead, which navigates within the current Ionic navigation stack.
212+
Using `navigate()` with delta values is not recommended in Ionic React because it follows the browser's linear history, which does not account for Ionic's non-linear tab and nested outlet navigation stacks. Use the `useIonRouter` hook's [`goBack()`](./utility-functions.md#back-navigation) method instead, which navigates within the current Ionic navigation stack.
221213

222214
## URL Parameters
223215

@@ -308,9 +300,9 @@ We recommend keeping your application as simple as possible until you need to ad
308300

309301
The two most common uses of non-linear routing is with tabs and nested `IonRouterOutlets`. We recommend only using non-linear routing if your application meets the tabs or nested router outlet use cases.
310302

311-
For more on tabs, please see [Working with Tabs](#working-with-tabs).
303+
For more on tabs, refer to [Working with Tabs](#working-with-tabs).
312304

313-
For more on nested router outlets, please see [Nested Routes](#nested-routes).
305+
For more on nested router outlets, refer to [Nested Routes](#nested-routes).
314306

315307
## Shared URLs versus Nested Routes
316308

@@ -351,12 +343,10 @@ const App: React.FC = () => (
351343
);
352344

353345
const DashboardRouterOutlet: React.FC = () => (
354-
<IonPage>
355-
<IonRouterOutlet>
356-
<Route index element={<DashboardMainPage />} />
357-
<Route path="stats" element={<DashboardStatsPage />} />
358-
</IonRouterOutlet>
359-
</IonPage>
346+
<IonRouterOutlet ionPage>
347+
<Route index element={<DashboardMainPage />} />
348+
<Route path="stats" element={<DashboardStatsPage />} />
349+
</IonRouterOutlet>
360350
);
361351
```
362352

@@ -509,7 +499,9 @@ The example below shows how the Spotify app reuses the same album component to s
509499

510500
## Live Example
511501

512-
If you would prefer to get hands on with the concepts and code described above, please checkout our [live example](https://stackblitz.com/edit/ionic-react-routing?file=src/index.tsx) of the topics above on StackBlitz.
502+
import NavigationPlayground from '@site/static/usage/v9/navigation/index.md';
503+
504+
<NavigationPlayground defaultFramework="react" />
513505

514506
### IonRouterOutlet in a Tabs View
515507

@@ -527,63 +519,8 @@ For example, the routes for a view with two tabs (sessions and speakers) can be
527519

528520
When a user navigates to a session detail page ("/sessions/1" for instance), `IonRouterOutlet` sees that both the list and detail pages share the same "sessions" path prefix and provides an animated page transition to the new view. If a user navigates to a different tab ("speakers" in this case), `IonRouterOutlet` knows not to provide the animation.
529521

530-
## Utilities
531-
532-
### useIonRouter
533-
534-
The `useIonRouter` hook gives you more control over routing in Ionic React, including custom page transition animations and Ionic-aware back navigation via `goBack()`.
535-
536-
The `useIonRouter` hook returns a `UseIonRouterResult` which has several convenience methods for routing:
537-
538-
```typescript
539-
type UseIonRouterResult = {
540-
/**
541-
* Navigates to a new pathname
542-
* @param pathname - The path to navigate to
543-
* @param routerDirection - Optional - The RouterDirection to use for transition purposes, defaults to 'forward'
544-
* @param routeAction - Optional - The RouteAction to use for history purposes, defaults to 'push'
545-
* @param routerOptions - Optional - Any additional parameters to pass to the router
546-
* @param animationBuilder - Optional - A custom transition animation to use
547-
*/
548-
push(
549-
pathname: string,
550-
routerDirection?: RouterDirection,
551-
routeAction?: RouteAction,
552-
routerOptions?: RouterOptions,
553-
animationBuilder?: AnimationBuilder
554-
): void;
555-
/**
556-
* Navigates backwards in history, using the IonRouter to determine history
557-
* @param animationBuilder - Optional - A custom transition animation to use
558-
*/
559-
goBack(animationBuilder?: AnimationBuilder): void;
560-
/**
561-
* Determines if there are any additional routes in the Router's history. However, routing is not prevented if the browser's history has more entries. Returns true if more entries exist, false if not.
562-
*/
563-
canGoBack(): boolean;
564-
/**
565-
* Information about the current route.
566-
*/
567-
routeInfo: RouteInfo;
568-
};
569-
```
570-
571-
The following example shows how to use `useIonRouter`:
572-
573-
```tsx
574-
import { useIonRouter } from '@ionic/react';
575-
576-
const MyComponent: React.FC = () => {
577-
const router = useIonRouter();
578-
const goToPage = () => {
579-
router.push('/my-page', 'root', 'replace');
580-
};
581-
582-
...
583-
}
584-
585-
```
586-
587522
## More Information
588523

589524
For more info on routing in React using the React Router implementation that Ionic uses under the hood, check out their docs at [https://reactrouter.com/6.28.0](https://reactrouter.com/6.28.0).
525+
526+
For documentation on `useIonRouter` and other utility functions, review [Utility Functions](./utility-functions.md).

‎docs/react/utility-functions.md‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
---
2+
title: Utility Functions
3+
sidebar_label: Utility Functions
4+
---
5+
6+
<head>
7+
<title>Ionic React Utility Functions</title>
8+
<meta
9+
name="description"
10+
content="Ionic React utility functions including useIonRouter for programmatic navigation with custom transitions, Ionic-aware back navigation, and routing history control."
11+
/>
12+
</head>
13+
14+
Ionic React provides utility functions for common tasks like programmatic navigation and controlling page transitions.
15+
16+
## Router
17+
18+
### Functions
19+
20+
#### useIonRouter
21+
22+
▸ **useIonRouter**(): [`UseIonRouterResult`](#useionrouterresult)
23+
24+
Returns the Ionic router instance, which provides methods for programmatic navigation with control over page transitions. Use this hook instead of React Router's `useNavigate` when you need to customize the transition animation or use Ionic-aware back navigation.
25+
26+
##### Customizing Page Transitions
27+
28+
```tsx
29+
import { useIonRouter } from '@ionic/react';
30+
import { customAnimation } from '../animations/customAnimation';
31+
32+
const MyComponent: React.FC = () => {
33+
const router = useIonRouter();
34+
35+
const goToPage = () => {
36+
router.push('/my-page', 'forward', 'push', undefined, customAnimation);
37+
};
38+
39+
const goBack = () => {
40+
router.goBack(customAnimation);
41+
};
42+
43+
...
44+
};
45+
```
46+
47+
##### Back Navigation
48+
49+
The `goBack()` method navigates within the current Ionic navigation stack, unlike React Router's `navigate(-1)` which follows the browser's linear history.
50+
51+
```tsx
52+
import { useIonRouter } from '@ionic/react';
53+
54+
const MyComponent: React.FC = () => {
55+
const router = useIonRouter();
56+
57+
const handleBack = () => {
58+
if (router.canGoBack()) {
59+
router.goBack();
60+
}
61+
};
62+
63+
...
64+
};
65+
```
66+
67+
##### canGoBack
68+
69+
Use `canGoBack()` to check whether there are additional routes in the Ionic router's history. This is useful when deciding whether to show a back button or handle the hardware back button on Android.
70+
71+
```tsx
72+
import { useIonRouter } from '@ionic/react';
73+
74+
const MyComponent: React.FC = () => {
75+
const router = useIonRouter();
76+
77+
// Returns true if more entries exist in Ionic's history stack
78+
const hasHistory = router.canGoBack();
79+
80+
...
81+
};
82+
```
83+
84+
##### navigateRoot
85+
86+
Use `navigateRoot()` to navigate to a new root pathname, clearing the navigation history and unmounting all previous views. After navigation, `canGoBack()` will return `false`. This is useful for navigating to a new root after login or logout.
87+
88+
```tsx
89+
import { useIonRouter } from '@ionic/react';
90+
91+
const MyComponent: React.FC = () => {
92+
const router = useIonRouter();
93+
94+
const handleLogout = () => {
95+
router.navigateRoot('/login');
96+
};
97+
98+
...
99+
};
100+
```
101+
102+
Review the [React Navigation Documentation](./navigation.md) for more navigation examples.
103+
104+
### Interfaces
105+
106+
#### UseIonRouterResult
107+
108+
```typescript
109+
import { AnimationBuilder, RouterDirection, RouteAction, RouterOptions, RouteInfo } from '@ionic/react';
110+
111+
type UseIonRouterResult = {
112+
/**
113+
* Navigates to a new pathname
114+
* @param pathname - The path to navigate to
115+
* @param routerDirection - Optional - The RouterDirection to use for transition purposes, defaults to 'forward'
116+
* @param routeAction - Optional - The RouteAction to use for history purposes, defaults to 'push'
117+
* @param routerOptions - Optional - Any additional parameters to pass to the router
118+
* @param animationBuilder - Optional - A custom transition animation to use
119+
*/
120+
push(
121+
pathname: string,
122+
routerDirection?: RouterDirection,
123+
routeAction?: RouteAction,
124+
routerOptions?: RouterOptions,
125+
animationBuilder?: AnimationBuilder
126+
): void;
127+
/**
128+
* Navigates backwards in history, using the IonRouter to determine history
129+
* @param animationBuilder - Optional - A custom transition animation to use
130+
*/
131+
goBack(animationBuilder?: AnimationBuilder): void;
132+
/**
133+
* Navigates to a new root pathname, clearing the navigation history and unmounting all previous views.
134+
* After navigation, canGoBack() will return false. Useful for navigating to a new root after login/logout.
135+
* @param pathname - The path to navigate to
136+
* @param animationBuilder - Optional - A custom transition animation to use
137+
*/
138+
navigateRoot(pathname: string, animationBuilder?: AnimationBuilder): void;
139+
/**
140+
* Determines if there are any additional routes in the Router's history. However, routing is not prevented if the browser's history has more entries. Returns true if more entries exist, false if not.
141+
*/
142+
canGoBack(): boolean;
143+
/**
144+
* Information about the current route.
145+
*/
146+
routeInfo: RouteInfo;
147+
/**
148+
* @deprecated Use goBack instead.
149+
* @param animationBuilder - Optional - A custom transition animation to use
150+
*/
151+
back(animationBuilder?: AnimationBuilder): void;
152+
};
153+
```

0 commit comments

Comments
 (0)