0
# Navigation APIs
1

2
Mini-program compatible navigation system with promise-based callbacks, page stack management, and URL processing for relative paths and custom routes.
3

4
## Capabilities
5

6
### navigateTo
7

8
Navigate to a new page while keeping the current page in the page stack. Supports event channels for page communication.
9

10
```typescript { .api }
11
/**
12
 * Navigate to a new page, keeping current page in stack
13
 * @param option - Navigation options with URL and callbacks
14
 * @returns Promise resolving to navigation result with event channel
15
 */
16
function navigateTo(option: Taro.navigateTo.Option): Promise<TaroGeneral.CallbackResult>;
17

18
interface NavigateToOption extends Base {
19
  /** Target page URL (relative or absolute) */
20
  url: string;
21
  /** Events to pass to target page via event channel */
22
  events?: Record<string, any>;
23
}
24
```
25

26
**Usage Examples:**
27

28
```typescript
29
import { navigateTo } from "@tarojs/router";
30

31
// Basic navigation
32
await navigateTo({
33
  url: "/profile?id=123",
34
  success: (res) => {
35
    console.log("Navigation successful", res);
36
    // res.eventChannel available for page communication
37
  },
38
  fail: (err) => console.error("Navigation failed", err),
39
  complete: () => console.log("Navigation completed")
40
});
41

42
// Navigation with event channel
43
await navigateTo({
44
  url: "/detail",
45
  events: {
46
    onDataUpdate: (data) => console.log("Received data", data),
47
    onError: (error) => console.error("Page error", error)
48
  }
49
});
50

51
// Relative path navigation
52
await navigateTo({
53
  url: "./subfolder/page" // Resolves relative to current page
54
});
55
```
56

57
### redirectTo
58

59
Redirect to a new page, replacing the current page in the stack. Current page will be unloaded.
60

61
```typescript { .api }
62
/**
63
 * Redirect to a new page, replacing current page
64
 * @param option - Navigation options with URL and callbacks
65
 * @returns Promise resolving to navigation result
66
 */
67
function redirectTo(option: Taro.redirectTo.Option): Promise<TaroGeneral.CallbackResult>;
68
```
69

70
**Usage Example:**
71

72
```typescript
73
import { redirectTo } from "@tarojs/router";
74

75
await redirectTo({
76
  url: "/login",
77
  success: () => console.log("Redirected to login"),
78
  fail: (err) => console.error("Redirect failed", err)
79
});
80
```
81

82
### navigateBack
83

84
Navigate back in the page stack by a specified delta (number of pages).
85

86
```typescript { .api }
87
/**
88
 * Navigate back in the page stack
89
 * @param option - Options with delta (defaults to {delta: 1})
90
 * @returns Promise resolving to navigation result
91
 */
92
function navigateBack(option?: Taro.navigateBack.Option): Promise<TaroGeneral.CallbackResult>;
93

94
interface NavigateBackOption extends Base {
95
  /** Number of pages to go back (minimum 1) */
96
  delta: number;
97
}
98
```
99

100
**Usage Examples:**
101

102
```typescript
103
import { navigateBack } from "@tarojs/router";
104

105
// Go back one page (default)
106
await navigateBack();
107

108
// Go back multiple pages
109
await navigateBack({
110
  delta: 2,
111
  success: () => console.log("Navigated back 2 pages"),
112
  fail: (err) => console.error("Navigate back failed", err)
113
});
114

115
// Go back to beginning of stack
116
await navigateBack({
117
  delta: 999 // Will go back to first page if stack is smaller
118
});
119
```
120

121
### switchTab
122

123
Switch to a tabbar page. If the target page is already in the tab cache, it will be shown instead of reloaded.
124

125
```typescript { .api }
126
/**
127
 * Switch to a tabbar page
128
 * @param option - Tab switch options with URL and callbacks
129
 * @returns Promise resolving to navigation result
130
 */
131
function switchTab(option: Taro.switchTab.Option): Promise<TaroGeneral.CallbackResult>;
132
```
133

134
**Usage Example:**
135

136
```typescript
137
import { switchTab } from "@tarojs/router";
138

139
await switchTab({
140
  url: "/home", // Must be a tabbar page
141
  success: () => console.log("Switched to home tab"),
142
  fail: (err) => console.error("Tab switch failed", err)
143
});
144
```
145

146
### reLaunch
147

148
Relaunch the app with a new page, clearing the entire page stack.
149

150
```typescript { .api }
151
/**
152
 * Relaunch app with a new page, clearing all page stack
153
 * @param option - Relaunch options with URL and callbacks
154
 * @returns Promise resolving to navigation result
155
 */
156
function reLaunch(option: Taro.reLaunch.Option): Promise<TaroGeneral.CallbackResult>;
157
```
158

159
**Usage Example:**
160

161
```typescript
162
import { reLaunch } from "@tarojs/router";
163

164
await reLaunch({
165
  url: "/welcome",
166
  success: () => console.log("App relaunched"),
167
  fail: (err) => console.error("Relaunch failed", err)
168
});
169
```
170

171
### getCurrentPages
172

173
Get the current page stack as an array of page instances. Not supported in multi-page mode.
174

175
```typescript { .api }
176
/**
177
 * Get current page stack (not supported in multi-page mode)
178
 * @returns Array of current page instances with route information
179
 */
180
function getCurrentPages(): Taro.Page[];
181
```
182

183
**Usage Example:**
184

185
```typescript
186
import { getCurrentPages } from "@tarojs/router";
187

188
const pages = getCurrentPages();
189
console.log("Current page stack:", pages);
190
console.log("Current page:", pages[pages.length - 1]);
191
console.log("Total pages in stack:", pages.length);
192

193
// Each page object contains:
194
// - route: string (page path without query parameters)
195
// - path: string (full path with query parameters)
196
// - options: any (page parameters)
197
```
198

199
## Callback Interface
200

201
```typescript { .api }
202
interface Base {
203
  /** Success callback function */
204
  success?: (...args: any[]) => void;
205
  /** Failure callback function */
206
  fail?: (...args: any[]) => void;
207
  /** Completion callback function (called regardless of success/failure) */
208
  complete?: (...args: any[]) => void;
209
}
210

211
interface Option extends Base {
212
  /** Target page URL (can be relative or absolute) */
213
  url: string;
214
}
215

216
interface NavigateOption extends Base {
217
  /** Target page URL */
218
  url: string;
219
  /** Events to pass to target page via event channel */
220
  events?: Record<string, any>;
221
}
222
```
223

224
## URL Processing Features
225

226
- **Relative Path Support**: Handles `./` and `../` path navigation relative to current page
227
- **Custom Route Aliases**: Processes custom route mappings defined in router configuration
228
- **Basename Handling**: Automatically prepends configured basename to paths
229
- **Query Parameter Support**: Preserves URL query parameters and hash fragments
230
- **Leading Slash Normalization**: Ensures all paths start with `/` for consistency