0
# React Native Tab View
1

2
React Native Tab View is a cross-platform Tab View component for React Native applications that enables developers to create swipeable, scrollable tab interfaces with smooth animations and gestures. It utilizes react-native-pager-view for native performance on Android and iOS platforms, while implementing PanResponder for web, macOS, and Windows compatibility.
3

4
## Package Information
5

6
- **Package Name**: react-native-tab-view
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install react-native-tab-view react-native-pager-view`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  TabView, 
16
  TabBar, 
17
  TabBarIndicator, 
18
  TabBarItem, 
19
  SceneMap,
20
  NavigationState, 
21
  Route,
22
  SceneRendererProps,
23
  TabDescriptor
24
} from "react-native-tab-view";
25

26
// Import type aliases if needed
27
import type { 
28
  TabViewProps, 
29
  TabBarProps, 
30
  TabBarIndicatorProps, 
31
  TabBarItemProps 
32
} from "react-native-tab-view";
33
```
34

35
For CommonJS:
36

37
```javascript
38
const { 
39
  TabView, 
40
  TabBar, 
41
  TabBarIndicator, 
42
  TabBarItem, 
43
  SceneMap 
44
} = require("react-native-tab-view");
45
```
46

47
## Basic Usage
48

49
```typescript
50
import React, { useState } from 'react';
51
import { View, Text } from 'react-native';
52
import { TabView, SceneMap, NavigationState, Route } from 'react-native-tab-view';
53

54
// Define route type
55
type TabRoute = Route & {
56
  title: string;
57
};
58

59
// Create scenes using SceneMap
60
const FirstRoute = () => (
61
  <View style={{ flex: 1, backgroundColor: '#ff4081' }}>
62
    <Text>First Tab Content</Text>
63
  </View>
64
);
65

66
const SecondRoute = () => (
67
  <View style={{ flex: 1, backgroundColor: '#673ab7' }}>
68
    <Text>Second Tab Content</Text>
69
  </View>
70
);
71

72
const renderScene = SceneMap({
73
  first: FirstRoute,
74
  second: SecondRoute,
75
});
76

77
export default function TabViewExample() {
78
  const [index, setIndex] = useState(0);
79
  const [routes] = useState<TabRoute[]>([
80
    { key: 'first', title: 'First' },
81
    { key: 'second', title: 'Second' },
82
  ]);
83

84
  return (
85
    <TabView
86
      navigationState={{ index, routes }}
87
      renderScene={renderScene}
88
      onIndexChange={setIndex}
89
      initialLayout={{ width: 375 }}
90
    />
91
  );
92
}
93
```
94

95
## Architecture
96

97
React Native Tab View is built around several key components:
98

99
- **TabView**: Main container component that manages navigation state and renders scenes
100
- **TabBar**: Default tab bar component with scrollable tabs and animated indicator  
101
- **SceneMap**: Helper for mapping route keys to React components
102
- **TabBarIndicator**: Animated indicator showing active tab position
103
- **TabBarItem**: Individual tab item with label, icon, and badge support
104
- **Type System**: Full TypeScript integration with generic route types
105

106
## Capabilities
107

108
### Tab View Component
109

110
Core container component that renders swipeable tab interface with navigation state management. Provides smooth animations, gesture support, and lazy loading capabilities.
111

112
```typescript { .api }
113
function TabView<T extends Route>({
114
  onIndexChange,
115
  navigationState,
116
  renderScene,
117
  renderTabBar,
118
  tabBarPosition,
119
  lazy,
120
  swipeEnabled,
121
  animationEnabled,
122
  ...props
123
}: Props<T>): JSX.Element;
124

125
interface Props<T extends Route> {
126
  /** Callback when tab index changes */
127
  onIndexChange: (index: number) => void;
128
  /** Optional callback when tab is selected (before index change) */
129
  onTabSelect?: (props: { index: number }) => void;
130
  /** Navigation state with current index and routes */
131
  navigationState: NavigationState<T>;
132
  /** Function to render scene content for each route */
133
  renderScene: (props: SceneRendererProps & { route: T }) => React.ReactNode;
134
  /** Optional placeholder renderer for lazy-loaded scenes */
135
  renderLazyPlaceholder?: (props: { route: T }) => React.ReactNode;
136
  /** Optional custom tab bar renderer */
137
  renderTabBar?: (props: SceneRendererProps & {
138
    navigationState: NavigationState<T>;
139
    options: Record<string, TabDescriptor<T>> | undefined;
140
  }) => React.ReactNode;
141
  /** Tab bar position - 'top' or 'bottom' */
142
  tabBarPosition?: 'top' | 'bottom';
143
  /** Enable lazy loading of scenes */
144
  lazy?: boolean | ((props: { route: T }) => boolean);
145
  /** Distance ahead to preload lazy scenes */
146
  lazyPreloadDistance?: number;
147
  /** Text direction override - 'ltr' or 'rtl' */
148
  direction?: LocaleDirection;
149
  /** Enable/disable swipe gestures */
150
  swipeEnabled?: boolean;
151
  /** Enable/disable animations */
152
  animationEnabled?: boolean;
153
  /** Initial layout dimensions */
154
  initialLayout?: Partial<Layout>;
155
  /** Style for the pager container */
156
  pagerStyle?: StyleProp<ViewStyle>;
157
  /** Style for the main container */
158
  style?: StyleProp<ViewStyle>;
159
  /** Per-route options for tab appearance and behavior */
160
  options?: Record<string, TabDescriptor<T>>;
161
  /** Common options applied to all tabs */
162
  commonOptions?: TabDescriptor<T>;
163
}
164
```
165

166
[Tab View Component](./tab-view.md)
167

168
### Tab Bar Component
169

170
Default tab bar implementation with scrollable tabs, animated indicator, and customizable styling. Handles tab press events and provides accessibility support.
171

172
```typescript { .api }
173
function TabBar<T extends Route>({
174
  navigationState,
175
  position,
176
  layout,
177
  jumpTo,
178
  scrollEnabled,
179
  renderIndicator,
180
  onTabPress,
181
  ...props
182
}: Props<T>): JSX.Element;
183

184
interface Props<T extends Route> extends SceneRendererProps {
185
  /** Navigation state */
186
  navigationState: NavigationState<T>;
187
  /** Enable horizontal scrolling */
188
  scrollEnabled?: boolean;
189
  /** Enable bounce effect on scrolling */
190
  bounces?: boolean;
191
  /** Active tab color */
192
  activeColor?: string;
193
  /** Inactive tab color */
194
  inactiveColor?: string;
195
  /** Press color for touch feedback */
196
  pressColor?: string;
197
  /** Press opacity for touch feedback */
198
  pressOpacity?: number;
199
  /** Per-route options for tab appearance */
200
  options?: Record<string, TabDescriptor<T>>;
201
  /** Custom indicator renderer */
202
  renderIndicator?: (props: IndicatorProps<T>) => React.ReactNode;
203
  /** Custom tab item renderer */
204
  renderTabBarItem?: (props: TabBarItemProps<T> & { key: string }) => React.ReactElement;
205
  /** Tab press event handler */
206
  onTabPress?: (scene: Scene<T> & Event) => void;
207
  /** Tab long press event handler */
208
  onTabLongPress?: (scene: Scene<T>) => void;
209
  /** Style for individual tabs */
210
  tabStyle?: StyleProp<ViewStyle>;
211
  /** Style for indicator */
212
  indicatorStyle?: StyleProp<ViewStyle>;
213
  /** Style for indicator container */
214
  indicatorContainerStyle?: StyleProp<ViewStyle>;
215
  /** Style for content container */
216
  contentContainerStyle?: StyleProp<ViewStyle>;
217
  /** Main container style */
218
  style?: StyleProp<ViewStyle>;
219
  /** Text direction for RTL support */
220
  direction?: LocaleDirection;
221
  /** Gap between tabs */
222
  gap?: number;
223
  /** Test identifier */
224
  testID?: string;
225
  /** Android ripple configuration */
226
  android_ripple?: PressableAndroidRippleConfig;
227
}
228
```
229

230
[Tab Bar Component](./tab-bar.md)
231

232
### Tab Bar Indicator
233

234
Animated indicator component that highlights the currently active tab with smooth transitions and supports both fixed and dynamic width configurations.
235

236
```typescript { .api }
237
function TabBarIndicator<T extends Route>({
238
  navigationState,
239
  width,
240
  getTabWidth,
241
  direction,
242
  style,
243
  gap,
244
  children,
245
  ...props
246
}: Props<T>): JSX.Element;
247

248
interface Props<T extends Route> extends SceneRendererProps {
249
  /** Navigation state */
250
  navigationState: NavigationState<T>;
251
  /** Indicator width configuration */
252
  width: 'auto' | `${number}%` | number;
253
  /** Function to get tab width by index */
254
  getTabWidth: (index: number) => number;
255
  /** Text direction for RTL support */
256
  direction: LocaleDirection;
257
  /** Custom indicator styling */
258
  style?: StyleProp<ViewStyle>;
259
  /** Space between tabs */
260
  gap?: number;
261
}
262
```
263

264
[Tab Bar Indicator](./tab-bar-indicator.md)
265

266
### Tab Bar Item
267

268
Individual tab item component with support for labels, icons, badges, and custom rendering. Handles touch interactions and provides accessibility support.
269

270
```typescript { .api }
271
function TabBarItem<T extends Route>({
272
  route,
273
  navigationState,
274
  position,
275
  onPress,
276
  onLongPress,
277
  activeColor,
278
  inactiveColor,
279
  ...props
280
}: Props<T>): JSX.Element;
281

282
interface Props<T extends Route> extends TabDescriptor<T> {
283
  /** Route object */
284
  route: T;
285
  /** Navigation state */
286
  navigationState: NavigationState<T>;
287
  /** Animated position value */
288
  position: Animated.AnimatedInterpolation<number>;
289
  /** Press event handler */
290
  onPress: () => void;
291
  /** Long press event handler */
292
  onLongPress: () => void;
293
  /** Active tab color */
294
  activeColor?: string;
295
  /** Inactive tab color */
296
  inactiveColor?: string;
297
  /** Tab styling */
298
  style: StyleProp<ViewStyle>;
299
}
300
```
301

302
[Tab Bar Item](./tab-bar-item.md)
303

304
### Scene Mapping
305

306
Utility functions for mapping route keys to React components and rendering scenes efficiently.
307

308
```typescript { .api }
309
/**
310
 * Helper function to create scene renderers from component mapping
311
 * @param scenes - Object mapping route keys to React components
312
 * @returns Scene renderer function compatible with TabView
313
 */
314
function SceneMap<T>(scenes: { [key: string]: React.ComponentType<T> }): 
315
  (props: SceneRendererProps & { route: Route }) => React.ReactElement;
316
```
317

318
[Scene Mapping](./scene-map.md)
319

320
## Core Types
321

322
```typescript { .api }
323
/** Navigation state interface */
324
interface NavigationState<T extends Route> {
325
  /** Current active tab index */
326
  index: number;
327
  /** Array of route objects */
328
  routes: T[];
329
}
330

331
/** Base route interface */
332
interface Route {
333
  /** Unique route identifier */
334
  key: string;
335
  /** Optional tab title */
336
  title?: string;
337
  /** Optional icon identifier */
338
  icon?: string;
339
  /** Optional accessibility label */
340
  accessibilityLabel?: string;
341
  /** Optional test ID */
342
  testID?: string;
343
  /** Optional accessibility flag */
344
  accessible?: boolean;
345
}
346

347
/** Layout dimensions */
348
interface Layout {
349
  /** Width in pixels */
350
  width: number;
351
  /** Height in pixels */
352
  height: number;
353
}
354

355
/** Props passed to scene renderers */
356
interface SceneRendererProps {
357
  /** Current layout dimensions */
358
  layout: Layout;
359
  /** Animated position value */
360
  position: Animated.AnimatedInterpolation<number>;
361
  /** Function to navigate to route */
362
  jumpTo: (key: string) => void;
363
}
364

365
/** Scene context object */
366
interface Scene<T extends Route> {
367
  route: T;
368
}
369

370
/** Event object with prevention capability */
371
interface Event {
372
  defaultPrevented: boolean;
373
  preventDefault(): void;
374
}
375

376
/** Text direction enumeration */
377
type LocaleDirection = 'ltr' | 'rtl';
378

379
/** Tab configuration object */
380
interface TabDescriptor<T extends Route> {
381
  /** Accessibility label override */
382
  accessibilityLabel?: string;
383
  /** Accessibility enabled flag */
384
  accessible?: boolean;
385
  /** Test identifier */
386
  testID?: string;
387
  /** Tab label text override */
388
  labelText?: string;
389
  /** Allow font scaling for label */
390
  labelAllowFontScaling?: boolean;
391
  /** Web navigation href */
392
  href?: string;
393
  /** Custom label renderer function */
394
  label?: (props: {
395
    route: T;
396
    labelText?: string;
397
    focused: boolean;
398
    color: string;
399
    allowFontScaling?: boolean;
400
    style?: StyleProp<TextStyle>;
401
  }) => React.ReactNode;
402
  /** Label text styling */
403
  labelStyle?: StyleProp<TextStyle>;
404
  /** Custom icon renderer function */
405
  icon?: (props: {
406
    route: T;
407
    focused: boolean;
408
    color: string;
409
    size: number;
410
  }) => React.ReactNode;
411
  /** Custom badge renderer function */
412
  badge?: (props: { route: T }) => React.ReactElement;
413
  /** Scene container styling */
414
  sceneStyle?: StyleProp<ViewStyle>;
415
}
416
```
417

418
## Props Type Aliases
419

420
```typescript { .api }
421
/** TypeScript type alias for TabView component props */
422
type TabViewProps<T extends Route> = Props<T>; // from TabView
423

424
/** TypeScript type alias for TabBar component props */
425
type TabBarProps<T extends Route> = Props<T>; // from TabBar
426

427
/** TypeScript type alias for TabBarIndicator component props */
428
type TabBarIndicatorProps<T extends Route> = Props<T>; // from TabBarIndicator
429

430
/** TypeScript type alias for TabBarItem component props */
431
type TabBarItemProps<T extends Route> = Props<T>; // from TabBarItem
432
```
433

434
## Additional Types
435

436
```typescript { .api }
437
/** Listener function for animated value changes */
438
type Listener = (value: number) => void;
439

440
/** Props for event emitter functionality */
441
interface EventEmitterProps {
442
  /** Add listener for enter events */
443
  addEnterListener: (listener: Listener) => () => void;
444
}
445

446
/** Props for Pager component (internal) */
447
type PagerProps = Omit<
448
  PagerViewProps,
449
  | 'initialPage'
450
  | 'scrollEnabled'
451
  | 'onPageScroll'
452
  | 'onPageSelected'
453
  | 'onPageScrollStateChanged'
454
  | 'keyboardDismissMode'
455
  | 'children'
456
> & {
457
  /** Keyboard dismissal behavior */
458
  keyboardDismissMode?: 'none' | 'on-drag' | 'auto';
459
  /** Enable/disable swipe gestures */
460
  swipeEnabled?: boolean;
461
  /** Enable/disable animations */
462
  animationEnabled?: boolean;
463
  /** Callback when swipe starts */
464
  onSwipeStart?: () => void;
465
  /** Callback when swipe ends */
466
  onSwipeEnd?: () => void;
467
};
468
```