0
# @tarojs/router
1

2
@tarojs/router is a comprehensive H5 routing system for the Taro cross-platform framework, providing compatibility with mini-program routing specifications. It supports both single-page (SPA) and multi-page (MPA) application modes, includes navigation APIs, history management, and UI components for creating web applications that follow mini-program conventions.
3

4
## Package Information
5

6
- **Package Name**: @tarojs/router
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @tarojs/router`
10
- **Node Version**: >= 18
11

12
## Core Imports
13

14
```typescript
15
import { createRouter, createMultiRouter } from "@tarojs/router";
16
```
17

18
For navigation APIs:
19

20
```typescript
21
import { navigateTo, navigateBack, redirectTo, switchTab, reLaunch } from "@tarojs/router";
22
```
23

24
For history management:
25

26
```typescript
27
import { setHistoryMode, setHistory, createMpaHistory, prependBasename } from "@tarojs/router";
28
```
29

30
For standard history creation:
31

32
```typescript
33
import { createBrowserHistory, createHashHistory } from "@tarojs/router";
34
```
35

36
## Basic Usage
37

38
### Single-Page Application Router
39

40
```typescript
41
import { createRouter, setHistoryMode } from "@tarojs/router";
42

43
// Set up history mode (hash, browser, or multi)
44
setHistoryMode("hash", "/");
45

46
// Create SPA router
47
const router = createRouter(history, app, {
48
  routes: [
49
    { path: "/home", load: () => import("./pages/home") },
50
    { path: "/profile", load: () => import("./pages/profile") }
51
  ],
52
  router: {
53
    mode: "hash",
54
    basename: "/",
55
    pathname: "/home"
56
  },
57
  pages: ["/home", "/profile"]
58
}, "react");
59
```
60

61
### Navigation
62

63
```typescript
64
import { navigateTo, navigateBack } from "@tarojs/router";
65

66
// Navigate to a new page
67
await navigateTo({
68
  url: "/profile?id=123",
69
  success: (res) => console.log("Navigation successful"),
70
  fail: (err) => console.error("Navigation failed", err)
71
});
72

73
// Navigate back
74
await navigateBack({
75
  delta: 1 // Number of pages to go back
76
});
77
```
78

79
## Architecture
80

81
@tarojs/router is built around several key components:
82

83
- **Router Engines**: SPA and MPA router implementations with page lifecycle management
84
- **Navigation API**: Mini-program compatible navigation functions (navigateTo, redirectTo, etc.)
85
- **History Management**: Browser and hash history with custom MPA history implementation
86
- **Application Mounting**: Functions to mount the app with or without tabbar support
87
- **Utility Functions**: Route alias management, navigation bar control, and mobile detection
88

89
## Capabilities
90

91
### Router Creation
92

93
Core router creation functions for SPA and MPA applications with full lifecycle support and page stack management.
94

95
```typescript { .api }
96
function createRouter(
97
  history: History,
98
  app: AppInstance,
99
  config: SpaRouterConfig,
100
  framework?: string
101
): () => void;
102

103
function createMultiRouter(
104
  history: History,
105
  app: AppInstance,
106
  config: MpaRouterConfig,
107
  framework?: string
108
): Promise<void>;
109
```
110

111
[Router Creation](./router-creation.md)
112

113
### Navigation APIs
114

115
Mini-program compatible navigation system with promise-based callbacks and page stack management.
116

117
```typescript { .api }
118
function navigateTo(option: Taro.navigateTo.Option): Promise<TaroGeneral.CallbackResult>;
119
function redirectTo(option: Taro.redirectTo.Option): Promise<TaroGeneral.CallbackResult>;
120
function navigateBack(option?: Taro.navigateBack.Option): Promise<TaroGeneral.CallbackResult>;
121
function switchTab(option: Taro.switchTab.Option): Promise<TaroGeneral.CallbackResult>;
122
function reLaunch(option: Taro.reLaunch.Option): Promise<TaroGeneral.CallbackResult>;
123
```
124

125
[Navigation APIs](./navigation-apis.md)
126

127
### History Management
128

129
Browser history abstraction with support for hash, browser, and multi-page modes with custom routing behavior.
130

131
```typescript { .api }
132
function setHistoryMode(mode?: IH5RouterConfig['mode'], base?: string): void;
133
function setHistory(h: History, base?: string): void;
134
function createMpaHistory(options?: HashHistoryOptions | BrowserHistoryOptions): MpaHistory;
135
function prependBasename(url?: string): string;
136
```
137

138
[History Management](./history-management.md)
139

140
### Application Mounting
141

142
Application mounting functions for setting up the H5 app with or without tabbar support.
143

144
```typescript { .api }
145
function handleAppMount(config: SpaRouterConfig | MpaRouterConfig, history: History, appId?: string): void;
146
function handleAppMountWithTabbar(config: SpaRouterConfig | MpaRouterConfig, history: History, appId?: string): void;
147
```
148

149
[Application Mounting](./application-mounting.md)
150

151
### Utility Functions
152

153
Navigation bar control, mobile detection, and route alias management utilities.
154

155
```typescript { .api }
156
function setTitle(title: string): void;
157
function setNavigationBarStyle(option: { backgroundColor: string; frontColor: string }): void;
158
function setNavigationBarLoading(loading: boolean): void;
159
function getCurrentPages(): Taro.Page[];
160
```
161

162
[Utility Functions](./utility-functions.md)
163

164
## Core Types
165

166
```typescript { .api }
167
interface SpaRouterConfig extends AppConfig {
168
  routes: Route[];
169
  router: Router;
170
  PullDownRefresh?: any;
171
}
172

173
interface MpaRouterConfig extends AppConfig {
174
  route: Route;
175
  pageName: string;
176
  router: Router;
177
  PullDownRefresh?: any;
178
}
179

180
interface Route extends PageConfig {
181
  path?: string;
182
  load?: () => Promise<any>;
183
}
184

185
interface Router {
186
  mode: IH5RouterConfig['mode'];
187
  basename: string;
188
  customRoutes?: Record<string, string | string[]>;
189
  pathname: string;
190
  forcePath?: string;
191
  enhanceAnimation?: boolean;
192
}
193
```