0
# React Navigation Bottom Tabs
1

2
React Navigation Bottom Tabs provides a bottom tab navigator component that follows iOS design guidelines. It enables developers to create tab-based navigation interfaces with smooth transitions, animations, and extensive customization options for React Native applications.
3

4
## Package Information
5

6
- **Package Name**: @react-navigation/bottom-tabs
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @react-navigation/bottom-tabs`
10

11
**Required Dependencies:**
12

13
```bash
14
npm install @react-navigation/native react-native-safe-area-context react-native-screens
15
```
16

17
**Peer Dependencies:**
18
- `@react-navigation/native`: workspace:^
19
- `react`: >= 18.2.0
20
- `react-native`: *
21
- `react-native-safe-area-context`: >= 4.0.0
22
- `react-native-screens`: >= 4.0.0
23

24
## Core Imports
25

26
```typescript
27
import { createBottomTabNavigator } from "@react-navigation/bottom-tabs";
28
```
29

30
For additional utilities and customization:
31

32
```typescript
33
import {
34
  createBottomTabNavigator,
35
  BottomTabBar,
36
  BottomTabView,
37
  useBottomTabBarHeight,
38
  BottomTabBarHeightContext,
39
  BottomTabBarHeightCallbackContext,
40
  SceneStyleInterpolators,
41
  TransitionPresets,
42
  TransitionSpecs,
43
  type BottomTabNavigationProp,
44
  type BottomTabScreenProps,
45
  type BottomTabNavigationOptions,
46
  type BottomTabBarButtonProps,
47
  type BottomTabBarProps,
48
  type BottomTabHeaderProps,
49
  type BottomTabNavigationEventMap,
50
  type BottomTabNavigatorProps,
51
  type BottomTabOptionsArgs,
52
} from "@react-navigation/bottom-tabs";
53
```
54

55
## Basic Usage
56

57
```typescript
58
import { createBottomTabNavigator } from "@react-navigation/bottom-tabs";
59
import { NavigationContainer } from "@react-navigation/native";
60

61
// Define your screen param types
62
type RootTabParamList = {
63
  Home: undefined;
64
  Settings: undefined;
65
  Profile: { userId: string };
66
};
67

68
const Tab = createBottomTabNavigator<RootTabParamList>();
69

70
function App() {
71
  return (
72
    <NavigationContainer>
73
      <Tab.Navigator>
74
        <Tab.Screen name="Home" component={HomeScreen} />
75
        <Tab.Screen 
76
          name="Settings" 
77
          component={SettingsScreen}
78
          options={{
79
            tabBarIcon: ({ color, size }) => (
80
              <Icon name="settings" color={color} size={size} />
81
            ),
82
          }}
83
        />
84
        <Tab.Screen 
85
          name="Profile" 
86
          component={ProfileScreen}
87
          options={{
88
            tabBarBadge: 3,
89
            tabBarLabel: "My Profile",
90
          }}
91
        />
92
      </Tab.Navigator>
93
    </NavigationContainer>
94
  );
95
}
96
```
97

98
## Architecture
99

100
React Navigation Bottom Tabs is built around several key components:
101

102
- **Navigator Factory**: `createBottomTabNavigator` creates typed navigators with Screen and Navigator components
103
- **View System**: `BottomTabView` manages screen rendering and `BottomTabBar` handles tab display
104
- **Navigation Integration**: Full integration with React Navigation's core navigation system and TypeScript support
105
- **Animation System**: Configurable transitions and scene interpolators for smooth tab switching
106
- **Customization Framework**: Extensive theming, styling, and behavior customization options
107

108
## Capabilities
109

110
### Navigator Creation
111

112
Core navigation functionality for creating bottom tab navigators with full TypeScript support and extensive configuration options.
113

114
```typescript { .api }
115
function createBottomTabNavigator<
116
  const ParamList extends ParamListBase,
117
  const NavigatorID extends string | undefined = undefined,
118
  const TypeBag extends NavigatorTypeBagBase = {
119
    ParamList: ParamList;
120
    NavigatorID: NavigatorID;
121
    State: TabNavigationState<ParamList>;
122
    ScreenOptions: BottomTabNavigationOptions;
123
    EventMap: BottomTabNavigationEventMap;
124
    NavigationList: {
125
      [RouteName in keyof ParamList]: BottomTabNavigationProp<
126
        ParamList,
127
        RouteName,
128
        NavigatorID
129
      >;
130
    };
131
    Navigator: typeof BottomTabNavigator;
132
  },
133
  const Config extends StaticConfig<TypeBag> = StaticConfig<TypeBag>
134
>(config?: Config): TypedNavigator<TypeBag, Config>;
135
```
136

137
[Navigator Creation](./navigator-creation.md)
138

139
### Tab Bar Customization
140

141
Comprehensive tab bar customization including appearance, behavior, animations, and custom components.
142

143
```typescript { .api }
144
interface BottomTabNavigationOptions {
145
  tabBarLabel?: string | ((props: {
146
    focused: boolean;
147
    color: string;
148
    position: LabelPosition;
149
    children: string;
150
  }) => React.ReactNode);
151
  tabBarIcon?: (props: {
152
    focused: boolean;
153
    color: string;
154
    size: number;
155
  }) => React.ReactNode;
156
  tabBarBadge?: number | string;
157
  tabBarButton?: (props: BottomTabBarButtonProps) => React.ReactNode;
158
  tabBarStyle?: Animated.WithAnimatedValue<StyleProp<ViewStyle>>;
159
  tabBarActiveTintColor?: string;
160
  tabBarInactiveTintColor?: string;
161
  tabBarHideOnKeyboard?: boolean;
162
  tabBarVariant?: Variant;
163
  tabBarPosition?: 'bottom' | 'left' | 'right' | 'top';
164
}
165
```
166

167
[Tab Bar Customization](./tab-bar-customization.md)
168

169
### Screen Configuration
170

171
Screen-level configuration options including animations, lazy loading, headers, and behavior control.
172

173
```typescript { .api }
174
interface BottomTabNavigationOptions {
175
  lazy?: boolean;
176
  freezeOnBlur?: boolean;
177
  popToTopOnBlur?: boolean;
178
  animation?: TabAnimationName;
179
  sceneStyleInterpolator?: BottomTabSceneStyleInterpolator;
180
  transitionSpec?: TransitionSpec;
181
  header?: (props: BottomTabHeaderProps) => React.ReactNode;
182
  headerShown?: boolean;
183
  sceneStyle?: StyleProp<ViewStyle>;
184
}
185
```
186

187
[Screen Configuration](./screen-configuration.md)
188

189
### Navigation and Routing
190

191
Navigation capabilities including programmatic navigation, event handling, and route management.
192

193
```typescript { .api }
194
interface BottomTabNavigationProp<
195
  ParamList extends ParamListBase,
196
  RouteName extends keyof ParamList = keyof ParamList,
197
  NavigatorID extends string | undefined = undefined
198
> extends NavigationProp<
199
  ParamList,
200
  RouteName,
201
  NavigatorID,
202
  TabNavigationState<ParamList>,
203
  BottomTabNavigationOptions,
204
  BottomTabNavigationEventMap
205
>, TabActionHelpers<ParamList> {}
206

207
interface BottomTabNavigationEventMap {
208
  tabPress: { data: undefined; canPreventDefault: true };
209
  tabLongPress: { data: undefined };
210
  transitionStart: { data: undefined };
211
  transitionEnd: { data: undefined };
212
}
213
```
214

215
[Navigation and Routing](./navigation-routing.md)
216

217
### Utilities and Hooks
218

219
Utility functions and React hooks for accessing tab bar dimensions, managing contexts, and integrating with the tab navigation system.
220

221
```typescript { .api }
222
function useBottomTabBarHeight(): number;
223

224
const BottomTabBarHeightContext: React.Context<number | undefined>;
225
const BottomTabBarHeightCallbackContext: React.Context<((height: number) => void) | undefined>;
226
```
227

228
[Utilities and Hooks](./utilities-hooks.md)
229

230
### Animation and Transitions
231

232
Built-in animation presets and custom transition configurations for smooth tab switching experiences.
233

234
```typescript { .api }
235
const SceneStyleInterpolators: {
236
  forFade: BottomTabSceneStyleInterpolator;
237
  forShift: BottomTabSceneStyleInterpolator;
238
};
239

240
const TransitionPresets: {
241
  FadeTransition: BottomTabTransitionPreset;
242
  ShiftTransition: BottomTabTransitionPreset;
243
};
244

245
const TransitionSpecs: {
246
  FadeSpec: TransitionSpec;
247
  ShiftSpec: TransitionSpec;
248
};
249
```
250

251
[Animation and Transitions](./animations-transitions.md)
252

253
## Types
254

255
### Core Types
256

257
```typescript { .api }
258
type ParamListBase = Record<string, object | undefined>;
259

260
type Layout = { width: number; height: number };
261

262
type Variant = 'uikit' | 'material';
263

264
type LabelPosition = 'beside-icon' | 'below-icon';
265

266
type TabAnimationName = 'none' | 'fade' | 'shift';
267
```
268

269
### Screen Props
270

271
```typescript { .api }
272
interface BottomTabScreenProps<
273
  ParamList extends ParamListBase,
274
  RouteName extends keyof ParamList = keyof ParamList,
275
  NavigatorID extends string | undefined = undefined
276
> {
277
  navigation: BottomTabNavigationProp<ParamList, RouteName, NavigatorID>;
278
  route: RouteProp<ParamList, RouteName>;
279
}
280
```
281

282
### Navigator Props
283

284
```typescript { .api }
285
interface BottomTabNavigatorProps extends DefaultNavigatorOptions<
286
  ParamListBase,
287
  string | undefined,
288
  TabNavigationState<ParamListBase>,
289
  BottomTabNavigationOptions,
290
  BottomTabNavigationEventMap,
291
  BottomTabNavigationProp<ParamListBase>
292
>, TabRouterOptions, BottomTabNavigationConfig {}
293
```
294

295
### Base Types
296

297
```typescript { .api }
298
type ParamListBase = Record<string, object | undefined>;
299

300
interface NavigatorTypeBagBase {
301
  ParamList: {};
302
  NavigatorID: string | undefined;
303
  State: NavigationState;
304
  ScreenOptions: {};
305
  EventMap: {};
306
  NavigationList: NavigationListBase<ParamListBase>;
307
  Navigator: React.ComponentType<any>;
308
}
309

310
interface TabNavigationState<ParamList extends ParamListBase> extends Omit<NavigationState<ParamList>, 'history'> {
311
  type: 'tab';
312
  history: { type: 'route'; key: string; params?: object | undefined }[];
313
  preloadedRouteKeys: string[];
314
}
315

316
interface NavigationState<ParamList extends ParamListBase = ParamListBase> {
317
  key: string;
318
  index: number;
319
  routeNames: Extract<keyof ParamList, string>[];
320
  history?: unknown[];
321
  routes: NavigationRoute<ParamList, keyof ParamList>[];
322
  type: string;
323
  stale: false;
324
}
325

326
interface StaticConfig<Bag extends NavigatorTypeBagBase> {
327
  screens?: StaticConfigScreens<
328
    Bag['ParamList'],
329
    Bag['State'],
330
    Bag['ScreenOptions'],
331
    Bag['EventMap'],
332
    Bag['NavigationList']
333
  >;
334
  groups?: Record<string, StaticConfigGroup<
335
    Bag['ParamList'],
336
    Bag['State'],
337
    Bag['ScreenOptions'],
338
    Bag['EventMap'],
339
    Bag['NavigationList']
340
  >>;
341
  config?: Config;
342
}
343

344
interface TypedNavigator<
345
  Bag extends NavigatorTypeBagBase,
346
  Config = unknown
347
> {
348
  Navigator: React.ComponentType<BottomTabNavigatorProps>;
349
  Screen: React.ComponentType<BottomTabScreenConfig<Bag>>;
350
  Group: React.ComponentType<GroupConfig>;
351
}
352

353
interface BottomTabScreenConfig<TypeBag> {
354
  name: keyof TypeBag['ParamList'];
355
  component?: React.ComponentType<any>;
356
  getComponent?: () => React.ComponentType<any>;
357
  options?: BottomTabNavigationOptions | ((props: BottomTabOptionsArgs) => BottomTabNavigationOptions);
358
  initialParams?: TypeBag['ParamList'][keyof TypeBag['ParamList']];
359
  getId?: ({ params }: { params: any }) => string;
360
  listeners?: BottomTabNavigationListeners;
361
}
362
```