Skip to content

Commit fa4901b

Browse files
ShaneKShaneK
authored
docs(react): add utility functions page with useIonRouter docs (#4455)
1 parent bee3752 commit fa4901b

File tree

4 files changed

+180
-68
lines changed

4 files changed

+180
-68
lines changed

‎docs/react/navigation.md‎

Lines changed: 12 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -71,17 +71,19 @@ const DashboardPage: React.FC = () => {
7171

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

74-
These routes are grouped in an `IonRouterOutlet`, let's discuss that next.
74+
These routes are grouped in an `IonRouterOutlet`.
7575

76-
## IonRouterOutlet
76+
## Components
77+
78+
### IonRouterOutlet
7779

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

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

8284
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`.
8385

84-
## Fallback Route
86+
### Fallback Route
8587

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

@@ -121,7 +123,7 @@ const DashboardPage: React.FC = () => {
121123
};
122124
```
123125

124-
## IonPage
126+
### IonPage
125127

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

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

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

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:
191+
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:
190192

191193
```tsx
192194
import { useNavigate } from 'react-router-dom';
@@ -217,7 +219,7 @@ Say you have the following application history:
217219

218220
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`.
219221

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.
222+
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.
221223

222224
## URL Parameters
223225

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

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

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

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

315317
## Shared URLs versus Nested Routes
316318

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

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

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-
587532
## More Information
588533

589534
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).
535+
536+
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+
```

‎docs/vue/utility-functions.md‎

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,15 @@
1-
# Utility Functions
1+
---
2+
title: Utility Functions
3+
sidebar_label: Utility Functions
4+
---
5+
6+
<head>
7+
<title>Ionic Vue Utility Functions</title>
8+
<meta
9+
name="description"
10+
content="Ionic Vue utility functions including useIonRouter for programmatic navigation, useBackButton for hardware back button handling, and useKeyboard for on-screen keyboard state."
11+
/>
12+
</head>
213

314
Ionic Vue ships with several utility functions that you can use in your application to make certain tasks easier such as managing the on-screen keyboard and the hardware back button.
415

@@ -12,7 +23,7 @@ Ionic Vue ships with several utility functions that you can use in your applicat
1223

1324
Returns the Ionic router instance, containing API methods for navigating, customizing page transitions and routing context for native features. This function can be used in combination with the [`useRouter`](https://router.vuejs.org/api/index.html#userouter) from Vue.
1425

15-
**Customizing Page Transitions**
26+
##### Customizing Page Transitions
1627

1728
```js
1829
import { IonPage, useIonRouter } from '@ionic/vue';
@@ -27,7 +38,7 @@ const back = () => {
2738
};
2839
```
2940

30-
**Hardware back button on Android**
41+
##### Back Navigation
3142

3243
You may want to know if you are at the root page of the application when a user presses the hardware back button on Android.
3344

‎sidebars.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -129,6 +129,7 @@ module.exports = {
129129
'react/navigation',
130130
'react/virtual-scroll',
131131
'react/slides',
132+
'react/utility-functions',
132133
'react/platform',
133134
'react/pwa',
134135
'react/overlays',

0 commit comments

Comments
 (0)