0
# Utilities and Hooks
1

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

4
## Capabilities
5

6
### Tab Bar Height Hook
7

8
Access the current height of the bottom tab bar for layout calculations and positioning.
9

10
```typescript { .api }
11
/**
12
 * Hook to get the current height of the bottom tab bar.
13
 * Must be used within a Bottom Tab Navigator.
14
 * @returns The height of the tab bar in pixels
15
 * @throws Error if used outside of a Bottom Tab Navigator
16
 */
17
function useBottomTabBarHeight(): number;
18
```
19

20
**Usage Examples:**
21

22
```typescript
23
import { useBottomTabBarHeight } from "@react-navigation/bottom-tabs";
24
import { View, Text, StyleSheet } from "react-native";
25

26
function ScreenContent() {
27
  const tabBarHeight = useBottomTabBarHeight();
28
  
29
  return (
30
    <View style={[styles.container, { paddingBottom: tabBarHeight }]}>
31
      <Text>Content with proper tab bar spacing</Text>
32
      <Text>Tab bar height: {tabBarHeight}px</Text>
33
    </View>
34
  );
35
}
36

37
// Usage with absolute positioned elements
38
function FloatingButton() {
39
  const tabBarHeight = useBottomTabBarHeight();
40
  
41
  return (
42
    <TouchableOpacity
43
      style={[
44
        styles.floatingButton,
45
        { bottom: tabBarHeight + 20 }
46
      ]}
47
    >
48
      <Text>Floating Action</Text>
49
    </TouchableOpacity>
50
  );
51
}
52

53
const styles = StyleSheet.create({
54
  container: {
55
    flex: 1,
56
    justifyContent: 'center',
57
    alignItems: 'center',
58
  },
59
  floatingButton: {
60
    position: 'absolute',
61
    right: 20,
62
    backgroundColor: 'blue',
63
    padding: 15,
64
    borderRadius: 30,
65
  },
66
});
67
```
68

69
### Tab Bar Height Context
70

71
React context that provides the bottom tab bar height value.
72

73
```typescript { .api }
74
/**
75
 * React context that provides the bottom tab bar height.
76
 * The value is undefined when not within a Bottom Tab Navigator.
77
 */
78
const BottomTabBarHeightContext: React.Context<number | undefined>;
79
```
80

81
**Usage Examples:**
82

83
```typescript
84
import React from 'react';
85
import { BottomTabBarHeightContext } from "@react-navigation/bottom-tabs";
86

87
function CustomComponent() {
88
  const tabBarHeight = React.useContext(BottomTabBarHeightContext);
89
  
90
  if (tabBarHeight === undefined) {
91
    return <Text>Not in a tab navigator</Text>;
92
  }
93
  
94
  return (
95
    <View style={{ paddingBottom: tabBarHeight }}>
96
      <Text>Custom component with tab bar awareness</Text>
97
    </View>
98
  );
99
}
100

101
// Higher-order component usage
102
function withTabBarHeight<P extends object>(
103
  Component: React.ComponentType<P & { tabBarHeight?: number }>
104
) {
105
  return function WrappedComponent(props: P) {
106
    const tabBarHeight = React.useContext(BottomTabBarHeightContext);
107
    
108
    return <Component {...props} tabBarHeight={tabBarHeight} />;
109
  };
110
}
111

112
const EnhancedComponent = withTabBarHeight(MyComponent);
113
```
114

115
### Tab Bar Height Callback Context
116

117
React context that provides a callback function to update the tab bar height.
118

119
```typescript { .api }
120
/**
121
 * React context that provides a callback to update the tab bar height.
122
 * Used internally by the tab bar component to notify height changes.
123
 * The value is undefined when not within a Bottom Tab Navigator.
124
 */
125
const BottomTabBarHeightCallbackContext: React.Context<
126
  ((height: number) => void) | undefined
127
>;
128
```
129

130
**Usage Examples:**
131

132
```typescript
133
import React from 'react';
134
import { BottomTabBarHeightCallbackContext } from "@react-navigation/bottom-tabs";
135

136
function CustomTabBar({ children }) {
137
  const setTabBarHeight = React.useContext(BottomTabBarHeightCallbackContext);
138
  const [height, setHeight] = React.useState(0);
139
  
140
  const onLayout = (event) => {
141
    const { height: measuredHeight } = event.nativeEvent.layout;
142
    setHeight(measuredHeight);
143
    
144
    // Notify the context about height changes
145
    if (setTabBarHeight) {
146
      setTabBarHeight(measuredHeight);
147
    }
148
  };
149
  
150
  return (
151
    <View onLayout={onLayout}>
152
      {children}
153
      <Text>Tab bar height: {height}</Text>
154
    </View>
155
  );
156
}
157
```
158

159
### Tab Bar View Component
160

161
The main view component that renders tab content and manages screen transitions.
162

163
```typescript { .api }
164
interface BottomTabViewProps {
165
  state: TabNavigationState<ParamListBase>;
166
  navigation: NavigationHelpers<ParamListBase, BottomTabNavigationEventMap>;
167
  descriptors: BottomTabDescriptorMap;
168
  tabBar?: (props: BottomTabBarProps) => React.ReactNode;
169
  safeAreaInsets?: {
170
    top?: number;
171
    right?: number;
172
    bottom?: number;
173
    left?: number;
174
  };
175
  detachInactiveScreens?: boolean;
176
}
177

178
const BottomTabView: React.ComponentType<BottomTabViewProps>;
179
```
180

181
**Usage Examples:**
182

183
```typescript
184
import { BottomTabView } from "@react-navigation/bottom-tabs";
185

186
function CustomNavigator(props) {
187
  // Custom tab bar component
188
  const renderTabBar = (tabBarProps) => (
189
    <CustomTabBar {...tabBarProps} />
190
  );
191
  
192
  return (
193
    <BottomTabView
194
      {...props}
195
      tabBar={renderTabBar}
196
      safeAreaInsets={{ bottom: 20 }}
197
      detachInactiveScreens={true}
198
    />
199
  );
200
}
201
```
202

203
### Navigation Helpers
204

205
Access navigation helpers for programmatic navigation within the tab system.
206

207
```typescript { .api }
208
interface BottomTabNavigationHelpers extends NavigationHelpers<
209
  ParamListBase,
210
  BottomTabNavigationEventMap
211
>, TabActionHelpers<ParamListBase> {
212
  /**
213
   * Navigate to a tab
214
   */
215
  navigate<RouteName extends keyof ParamListBase>(
216
    name: RouteName,
217
    params?: ParamListBase[RouteName]
218
  ): void;
219
  
220
  /**
221
   * Jump to a tab
222
   */
223
  jumpTo<RouteName extends keyof ParamListBase>(
224
    name: RouteName,
225
    params?: ParamListBase[RouteName]
226
  ): void;
227
  
228
  /**
229
   * Emit a navigation event
230
   */
231
  emit<EventName extends keyof BottomTabNavigationEventMap>(
232
    event: EventName,
233
    data?: BottomTabNavigationEventMap[EventName]['data']
234
  ): void;
235
}
236
```
237

238
**Usage Examples:**
239

240
```typescript
241
function NavigationUtility({ navigation }) {
242
  const handleTabPress = (tabName) => {
243
    // Emit custom event before navigation
244
    navigation.emit('tabPress', undefined);
245
    
246
    // Navigate to tab
247
    navigation.jumpTo(tabName);
248
  };
249
  
250
  return (
251
    <View>
252
      <Button 
253
        title="Go to Home" 
254
        onPress={() => handleTabPress('Home')} 
255
      />
256
    </View>
257
  );
258
}
259
```
260

261
### Type Utilities
262

263
Helper types for working with bottom tab navigation TypeScript integration.
264

265
```typescript { .api }
266
/**
267
 * Extract screen props type for a specific route
268
 */
269
type BottomTabScreenProps<
270
  ParamList extends ParamListBase,
271
  RouteName extends keyof ParamList = keyof ParamList,
272
  NavigatorID extends string | undefined = undefined
273
> = {
274
  navigation: BottomTabNavigationProp<ParamList, RouteName, NavigatorID>;
275
  route: RouteProp<ParamList, RouteName>;
276
};
277

278
/**
279
 * Extract navigation prop type for a specific route
280
 */
281
type BottomTabNavigationProp<
282
  ParamList extends ParamListBase,
283
  RouteName extends keyof ParamList = keyof ParamList,
284
  NavigatorID extends string | undefined = undefined
285
> = NavigationProp<
286
  ParamList,
287
  RouteName,
288
  NavigatorID,
289
  TabNavigationState<ParamList>,
290
  BottomTabNavigationOptions,
291
  BottomTabNavigationEventMap
292
> & TabActionHelpers<ParamList>;
293

294
/**
295
 * Options arguments for screen configuration functions
296
 */
297
type BottomTabOptionsArgs<
298
  ParamList extends ParamListBase,
299
  RouteName extends keyof ParamList = keyof ParamList,
300
  NavigatorID extends string | undefined = undefined
301
> = BottomTabScreenProps<ParamList, RouteName, NavigatorID> & {
302
  theme: Theme;
303
};
304
```
305

306
**Usage Examples:**
307

308
```typescript
309
// Define your param list
310
type RootTabParamList = {
311
  Home: undefined;
312
  Profile: { userId: string };
313
  Settings: { section?: string };
314
};
315

316
// Use type utilities for component props
317
type HomeScreenProps = BottomTabScreenProps<RootTabParamList, 'Home'>;
318
type ProfileScreenProps = BottomTabScreenProps<RootTabParamList, 'Profile'>;
319

320
function HomeScreen({ navigation, route }: HomeScreenProps) {
321
  // navigation and route are properly typed
322
  return <View />;
323
}
324

325
function ProfileScreen({ navigation, route }: ProfileScreenProps) {
326
  // route.params is typed as { userId: string }
327
  const { userId } = route.params;
328
  return <View />;
329
}
330

331
// Navigation prop type for use in hooks or utilities
332
type HomeNavigationProp = BottomTabNavigationProp<RootTabParamList, 'Home'>;
333

334
function useHomeNavigation(): HomeNavigationProp {
335
  return useNavigation<HomeNavigationProp>();
336
}
337
```
338

339
### Layout Utilities
340

341
Utilities for working with layout dimensions and safe areas.
342

343
```typescript { .api }
344
/**
345
 * Layout dimensions type
346
 */
347
type Layout = {
348
  width: number;
349
  height: number;
350
};
351

352
/**
353
 * Safe area insets type for tab bar positioning
354
 */
355
interface SafeAreaInsets {
356
  top: number;
357
  right: number;
358
  bottom: number;
359
  left: number;
360
}
361
```
362

363
**Usage Examples:**
364

365
```typescript
366
import { useSafeAreaInsets } from 'react-native-safe-area-context';
367

368
function ResponsiveTabContent() {
369
  const insets = useSafeAreaInsets();
370
  const tabBarHeight = useBottomTabBarHeight();
371
  
372
  const contentStyle = {
373
    paddingTop: insets.top,
374
    paddingBottom: Math.max(insets.bottom, tabBarHeight),
375
    paddingLeft: insets.left,
376
    paddingRight: insets.right,
377
  };
378
  
379
  return (
380
    <ScrollView style={contentStyle}>
381
      <Text>Responsive content with proper safe area handling</Text>
382
    </ScrollView>
383
  );
384
}
385
```
386

387
### Base Types
388

389
```typescript { .api }
390
type ParamListBase = Record<string, object | undefined>;
391

392
interface TabNavigationState<ParamList extends ParamListBase> extends Omit<NavigationState<ParamList>, 'history'> {
393
  type: 'tab';
394
  history: { type: 'route'; key: string; params?: object | undefined }[];
395
  preloadedRouteKeys: string[];
396
}
397

398
interface NavigationState<ParamList extends ParamListBase = ParamListBase> {
399
  key: string;
400
  index: number;
401
  routeNames: Extract<keyof ParamList, string>[];
402
  history?: unknown[];
403
  routes: NavigationRoute<ParamList, keyof ParamList>[];
404
  type: string;
405
  stale: false;
406
}
407

408
interface BottomTabDescriptorMap {
409
  [key: string]: BottomTabDescriptor;
410
}
411

412
interface BottomTabDescriptor {
413
  render(): React.ReactNode;
414
  options: BottomTabNavigationOptions;
415
  navigation: BottomTabNavigationProp<ParamListBase>;
416
  route: RouteProp<ParamListBase>;
417
}
418
```