0
# Navigation
1

2
Navigation and routing components for building application navigation structures and managing page transitions.
3

4
## Capabilities
5

6
### Navigator
7

8
Basic navigation component for page transitions and routing within applications.
9

10
```typescript { .api }
11
/**
12
 * Navigation component for page transitions
13
 * @supported all platforms
14
 */
15
const Navigator: ComponentType<NavigatorProps>;
16

17
interface NavigatorProps extends StandardProps {
18
  /** Target page URL or path
19
   * @supported weapp, alipay, swan, tt, qq, jd, h5, rn, harmony_hybrid
20
   */
21
  url?: string;
22
  /** Navigation open type
23
   * @supported weapp, alipay, swan, tt, qq, jd, h5, rn, harmony_hybrid
24
   * @default "navigate"
25
   */
26
  openType?: keyof NavigatorProps.OpenType;
27
  /** Delta for navigateBack
28
   * @supported weapp, alipay, swan, tt, qq, jd, h5, rn, harmony_hybrid
29
   * @default 1
30
   */
31
  delta?: number;
32
  /** App ID for mini-program navigation
33
   * @supported weapp, tt, qq, jd
34
   */
35
  appId?: string;
36
  /** Target path within target mini-program
37
   * @supported weapp, tt, qq, jd
38
   */
39
  path?: string;
40
  /** Extra data passed to target page
41
   * @supported weapp, tt, qq, jd
42
   */
43
  extraData?: Record<string, any>;
44
  /** Version type for mini-program navigation
45
   * @supported weapp, tt, qq, jd
46
   * @default "release"
47
   */
48
  version?: 'develop' | 'trial' | 'release';
49
  /** Hover class name
50
   * @supported weapp, alipay, swan, tt, qq, jd
51
   * @default "navigator-hover"
52
   */
53
  hoverClass?: string;
54
  /** Hover start time in milliseconds
55
   * @supported weapp, alipay, swan, tt, qq, jd
56
   * @default 50
57
   */
58
  hoverStartTime?: number;
59
  /** Hover stay time in milliseconds
60
   * @supported weapp, alipay, swan, tt, qq, jd
61
   * @default 600
62
   */
63
  hoverStayTime?: number;
64
  /** Navigation success callback */
65
  onSuccess?: (event: NavigatorSuccessEvent) => void;
66
  /** Navigation fail callback */
67
  onFail?: (event: NavigatorFailEvent) => void;
68
  /** Navigation complete callback */
69
  onComplete?: (event: TaroEvent) => void;
70
}
71

72
declare namespace NavigatorProps {
73
  interface OpenType {
74
    /** Navigate to new page */
75
    navigate: '';
76
    /** Redirect to new page */
77
    redirect: '';
78
    /** Switch to tabbar page */
79
    switchTab: '';
80
    /** Relaunch application */
81
    reLaunch: '';
82
    /** Navigate back */
83
    navigateBack: '';
84
    /** Exit mini-program */
85
    exit: '';
86
    /** Navigate to mini-program */
87
    navigateToMiniProgram: '';
88
  }
89
}
90
```
91

92
### NavigationBar
93

94
Navigation bar component for customizing the top navigation area.
95

96
```typescript { .api }
97
/**
98
 * Navigation bar component
99
 * @supported weapp, tt, qq, jd
100
 */
101
const NavigationBar: ComponentType<NavigationBarProps>;
102

103
interface NavigationBarProps extends StandardProps {
104
  /** Navigation bar title
105
   * @supported weapp, tt, qq, jd
106
   */
107
  title?: string;
108
  /** Whether loading is shown
109
   * @supported weapp, tt, qq, jd
110
   * @default false
111
   */
112
  loading?: boolean;
113
  /** Front color for status bar and navigation bar
114
   * @supported weapp, tt, qq, jd
115
   * @default "#000000"
116
   */
117
  frontColor?: '#000000' | '#ffffff';
118
  /** Background color for navigation bar
119
   * @supported weapp, tt, qq, jd
120
   * @default "#ffffff"
121
   */
122
  backgroundColor?: string;
123
  /** Color animation duration in milliseconds
124
   * @supported weapp, tt, qq, jd
125
   * @default 0
126
   */
127
  colorAnimationDuration?: number;
128
  /** Color animation timing function
129
   * @supported weapp, tt, qq, jd
130
   * @default "linear"
131
   */
132
  colorAnimationTimingFunc?: 'linear' | 'easeIn' | 'easeOut' | 'easeInOut';
133
}
134
```
135

136
### FunctionalPageNavigator
137

138
Functional page navigator for specific mini-program features.
139

140
```typescript { .api }
141
/**
142
 * Functional page navigation component
143
 * @supported weapp, tt, qq, jd
144
 */
145
const FunctionalPageNavigator: ComponentType<FunctionalPageNavigatorProps>;
146

147
interface FunctionalPageNavigatorProps extends StandardProps {
148
  /** Functional page version
149
   * @supported weapp, tt, qq, jd
150
   * @default "release"
151
   */
152
  version?: 'develop' | 'trial' | 'release';
153
  /** Functional page name
154
   * @supported weapp, tt, qq, jd
155
   */
156
  name?: 'loginAndGetUserInfo' | 'requestPayment' | 'chooseAddress';
157
  /** Arguments passed to functional page
158
   * @supported weapp, tt, qq, jd
159
   */
160
  args?: Record<string, any>;
161
  /** Navigation success callback */
162
  onSuccess?: (event: FunctionalPageNavigatorSuccessEvent) => void;
163
  /** Navigation fail callback */
164
  onFail?: (event: FunctionalPageNavigatorFailEvent) => void;
165
  /** Navigation cancel callback */
166
  onCancel?: (event: TaroEvent) => void;
167
}
168
```
169

170
### Tabs
171

172
Tab navigation component for organizing content into multiple panels.
173

174
```typescript { .api }
175
/**
176
 * Tab navigation component
177
 * @supported weapp, tt, qq, jd, h5
178
 */
179
const Tabs: ComponentType<TabsProps>;
180

181
interface TabsProps extends StandardProps {
182
  /** Current active tab index
183
   * @supported weapp, tt, qq, jd, h5
184
   * @default 0
185
   */
186
  current?: number;
187
  /** Tab scroll threshold
188
   * @supported weapp, tt, qq, jd, h5
189
   * @default 5
190
   */
191
  scrollThreshold?: number;
192
  /** Tab data array
193
   * @supported weapp, tt, qq, jd, h5
194
   */
195
  tabList?: TabItem[];
196
  /** Tab click callback */
197
  onTabClick?: (event: TabsTabClickEvent) => void;
198
}
199

200
interface TabItem {
201
  /** Tab title */
202
  title: string;
203
  /** Tab icon URL */
204
  iconPath?: string;
205
  /** Selected tab icon URL */
206
  selectedIconPath?: string;
207
  /** Tab text */
208
  text?: string;
209
  /** Tab badge text */
210
  badge?: string;
211
  /** Tab red dot indicator */
212
  dot?: boolean;
213
}
214
```
215

216
**Usage Examples:**
217

218
```typescript
219
import { Navigator, NavigationBar, Tabs } from "@tarojs/components";
220

221
// Basic navigation
222
<Navigator url="/pages/detail/index" openType="navigate">
223
  Go to Detail Page
224
</Navigator>
225

226
// Tab navigation
227
const tabList = [
228
  { title: 'Home', iconPath: '/images/home.png' },
229
  { title: 'Profile', iconPath: '/images/profile.png' }
230
];
231

232
<Tabs 
233
  current={0} 
234
  tabList={tabList} 
235
  onTabClick={(e) => console.log('Tab clicked:', e.detail.index)}
236
/>
237

238
// Custom navigation bar
239
<NavigationBar 
240
  title="My App" 
241
  frontColor="#ffffff" 
242
  backgroundColor="#007AFF"
243
/>
244
```
245

246
## Advanced Navigation Patterns
247

248
### Page Navigation Flow
249

250
```typescript
251
// Navigation with data passing
252
<Navigator 
253
  url="/pages/detail/index?id=123&type=product"
254
  openType="navigate"
255
  onSuccess={(e) => console.log('Navigation successful')}
256
  onFail={(e) => console.log('Navigation failed:', e.detail.errMsg)}
257
>
258
  View Product Details
259
</Navigator>
260

261
// Tab bar navigation
262
<Navigator url="/pages/home/index" openType="switchTab">
263
  Go to Home Tab
264
</Navigator>
265

266
// Back navigation with custom delta
267
<Navigator openType="navigateBack" delta={2}>
268
  Go Back 2 Pages
269
</Navigator>
270
```
271

272
### Mini-Program Navigation
273

274
```typescript
275
// Navigate to another mini-program
276
<Navigator
277
  openType="navigateToMiniProgram"
278
  appId="wxABCDEF1234567890"
279
  path="pages/index/index"
280
  extraData={{ from: 'myapp' }}
281
  version="release"
282
  onSuccess={(e) => console.log('Mini-program opened')}
283
  onFail={(e) => console.log('Failed to open mini-program')}
284
>
285
  Open Other Mini-Program
286
</Navigator>
287

288
// Functional page navigation
289
<FunctionalPageNavigator
290
  name="requestPayment"
291
  args={{
292
    fee: 100,
293
    paymentType: 'wechat'
294
  }}
295
  onSuccess={(e) => console.log('Payment successful')}
296
  onFail={(e) => console.log('Payment failed')}
297
>
298
  Make Payment
299
</FunctionalPageNavigator>
300
```
301

302
## Types
303

304
```typescript { .api }
305
// Navigator event interfaces
306
interface NavigatorSuccessEvent extends TaroEvent {
307
  detail: {
308
    errMsg: string;
309
  };
310
}
311

312
interface NavigatorFailEvent extends TaroEvent {
313
  detail: {
314
    errMsg: string;
315
  };
316
}
317

318
// Functional page navigator event interfaces
319
interface FunctionalPageNavigatorSuccessEvent extends TaroEvent {
320
  detail: {
321
    errMsg: string;
322
    [key: string]: any;
323
  };
324
}
325

326
interface FunctionalPageNavigatorFailEvent extends TaroEvent {
327
  detail: {
328
    errMsg: string;
329
  };
330
}
331

332
// Tabs event interfaces
333
interface TabsTabClickEvent extends TaroEvent {
334
  detail: {
335
    index: number;
336
    title: string;
337
  };
338
}
339

340
// Navigation types
341
type NavigationOpenType = 
342
  | 'navigate' 
343
  | 'redirect' 
344
  | 'switchTab' 
345
  | 'reLaunch' 
346
  | 'navigateBack' 
347
  | 'exit' 
348
  | 'navigateToMiniProgram';
349

350
type NavigationBarFrontColor = '#000000' | '#ffffff';
351

352
type NavigationBarTimingFunction = 'linear' | 'easeIn' | 'easeOut' | 'easeInOut';
353

354
type FunctionalPageName = 
355
  | 'loginAndGetUserInfo' 
356
  | 'requestPayment' 
357
  | 'chooseAddress';
358

359
// Tab item interface
360
interface TabConfiguration {
361
  title: string;
362
  iconPath?: string;
363
  selectedIconPath?: string;
364
  text?: string;
365
  badge?: string;
366
  dot?: boolean;
367
}
368
```