|
| 1 | +--- |
| 2 | +title: Utility Functions |
| 3 | +sidebar_label: Utility Functions |
| 4 | +--- |
| 5 | + |
| 6 | +<head> |
| 7 | + <title>Ionic React Utility Functions: useIonRouter Hook</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 | +### useIonRouter |
| 19 | + |
| 20 | +▸ **useIonRouter**(): [`UseIonRouterResult`](#useionrouterresult) |
| 21 | + |
| 22 | +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. |
| 23 | + |
| 24 | +#### Customizing Page Transitions |
| 25 | + |
| 26 | +```tsx |
| 27 | +import { useIonRouter } from '@ionic/react'; |
| 28 | +import { customAnimation } from '../animations/customAnimation'; |
| 29 | + |
| 30 | +const MyComponent: React.FC = () => { |
| 31 | + const router = useIonRouter(); |
| 32 | + |
| 33 | + const goToPage = () => { |
| 34 | + router.push('/my-page', 'forward', 'push', undefined, customAnimation); |
| 35 | + }; |
| 36 | + |
| 37 | + const goBack = () => { |
| 38 | + router.goBack(customAnimation); |
| 39 | + }; |
| 40 | + |
| 41 | + ... |
| 42 | +}; |
| 43 | +``` |
| 44 | + |
| 45 | +#### Back Navigation |
| 46 | + |
| 47 | +The `goBack()` method navigates within the current Ionic navigation stack, unlike React Router's `navigate(-1)` which follows the browser's linear history. |
| 48 | + |
| 49 | +```tsx |
| 50 | +import { useIonRouter } from '@ionic/react'; |
| 51 | + |
| 52 | +const MyComponent: React.FC = () => { |
| 53 | + const router = useIonRouter(); |
| 54 | + |
| 55 | + const handleBack = () => { |
| 56 | + if (router.canGoBack()) { |
| 57 | + router.goBack(); |
| 58 | + } |
| 59 | + }; |
| 60 | + |
| 61 | + ... |
| 62 | +}; |
| 63 | +``` |
| 64 | + |
| 65 | +#### canGoBack |
| 66 | + |
| 67 | +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. |
| 68 | + |
| 69 | +```tsx |
| 70 | +import { useIonRouter } from '@ionic/react'; |
| 71 | + |
| 72 | +const MyComponent: React.FC = () => { |
| 73 | + const router = useIonRouter(); |
| 74 | + |
| 75 | + // Returns true if more entries exist in Ionic's history stack |
| 76 | + const hasHistory = router.canGoBack(); |
| 77 | + |
| 78 | + ... |
| 79 | +}; |
| 80 | +``` |
| 81 | + |
| 82 | +#### navigateRoot |
| 83 | + |
| 84 | +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. |
| 85 | + |
| 86 | +```tsx |
| 87 | +import { useIonRouter } from '@ionic/react'; |
| 88 | + |
| 89 | +const MyComponent: React.FC = () => { |
| 90 | + const router = useIonRouter(); |
| 91 | + |
| 92 | + const handleLogout = () => { |
| 93 | + router.navigateRoot('/login'); |
| 94 | + }; |
| 95 | + |
| 96 | + ... |
| 97 | +}; |
| 98 | +``` |
| 99 | + |
| 100 | +See the [React Navigation Documentation](./navigation) for more navigation examples. |
| 101 | + |
| 102 | +### Interfaces |
| 103 | + |
| 104 | +#### UseIonRouterResult |
| 105 | + |
| 106 | +```typescript |
| 107 | +import { AnimationBuilder, RouterDirection, RouteAction, RouterOptions, RouteInfo } from '@ionic/react'; |
| 108 | + |
| 109 | +type UseIonRouterResult = { |
| 110 | + /** |
| 111 | + * Navigates to a new pathname |
| 112 | + * @param pathname - The path to navigate to |
| 113 | + * @param routerDirection - Optional - The RouterDirection to use for transition purposes, defaults to 'forward' |
| 114 | + * @param routeAction - Optional - The RouteAction to use for history purposes, defaults to 'push' |
| 115 | + * @param routerOptions - Optional - Any additional parameters to pass to the router |
| 116 | + * @param animationBuilder - Optional - A custom transition animation to use |
| 117 | + */ |
| 118 | + push( |
| 119 | + pathname: string, |
| 120 | + routerDirection?: RouterDirection, |
| 121 | + routeAction?: RouteAction, |
| 122 | + routerOptions?: RouterOptions, |
| 123 | + animationBuilder?: AnimationBuilder |
| 124 | + ): void; |
| 125 | + /** |
| 126 | + * Navigates backwards in history, using the IonRouter to determine history |
| 127 | + * @param animationBuilder - Optional - A custom transition animation to use |
| 128 | + */ |
| 129 | + goBack(animationBuilder?: AnimationBuilder): void; |
| 130 | + /** |
| 131 | + * Navigates to a new root pathname, clearing the navigation history and unmounting all previous views. |
| 132 | + * After navigation, canGoBack() will return false. Useful for navigating to a new root after login/logout. |
| 133 | + * @param pathname - The path to navigate to |
| 134 | + * @param animationBuilder - Optional - A custom transition animation to use |
| 135 | + */ |
| 136 | + navigateRoot(pathname: string, animationBuilder?: AnimationBuilder): void; |
| 137 | + /** |
| 138 | + * 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. |
| 139 | + */ |
| 140 | + canGoBack(): boolean; |
| 141 | + /** |
| 142 | + * Information about the current route. |
| 143 | + */ |
| 144 | + routeInfo: RouteInfo; |
| 145 | + /** |
| 146 | + * @deprecated Use goBack instead. |
| 147 | + * @param animationBuilder - Optional - A custom transition animation to use |
| 148 | + */ |
| 149 | + back(animationBuilder?: AnimationBuilder): void; |
| 150 | +}; |
| 151 | +``` |
0 commit comments