0
# Tab Bar Customization
1

2
Comprehensive tab bar customization including appearance, behavior, animations, and custom components for creating highly customized bottom tab navigation experiences.
3

4
## Capabilities
5

6
### Tab Label Configuration
7

8
Customize the display and behavior of tab labels.
9

10
```typescript { .api }
11
interface TabLabelOptions {
12
  /**
13
   * Title string of a tab displayed in the tab bar or a function that returns a React.Node.
14
   * When undefined, scene title is used.
15
   */
16
  tabBarLabel?: string | ((props: {
17
    focused: boolean;
18
    color: string;
19
    position: LabelPosition;
20
    children: string;
21
  }) => React.ReactNode);
22
  
23
  /**
24
   * Whether the tab label should be visible. Defaults to `true`.
25
   */
26
  tabBarShowLabel?: boolean;
27
  
28
  /**
29
   * Whether the label is shown below the icon or beside the icon.
30
   * By default, the position is chosen automatically based on device width.
31
   */
32
  tabBarLabelPosition?: LabelPosition;
33
  
34
  /**
35
   * Style object for the tab label.
36
   */
37
  tabBarLabelStyle?: StyleProp<TextStyle>;
38
  
39
  /**
40
   * Whether label font should scale to respect Text Size accessibility settings.
41
   */
42
  tabBarAllowFontScaling?: boolean;
43
}
44

45
type LabelPosition = 'beside-icon' | 'below-icon';
46
```
47

48
**Usage Examples:**
49

50
```typescript
51
<Tab.Screen
52
  name="Home"
53
  component={HomeScreen}
54
  options={{
55
    tabBarLabel: 'My Home',
56
    tabBarLabelStyle: {
57
      fontSize: 12,
58
      fontWeight: 'bold',
59
    },
60
    tabBarLabelPosition: 'below-icon',
61
    tabBarAllowFontScaling: false,
62
  }}
63
/>
64

65
// Dynamic label
66
<Tab.Screen
67
  name="Messages"
68
  component={MessagesScreen}
69
  options={{
70
    tabBarLabel: ({ focused, color }) => (
71
      <Text style={{ color, fontWeight: focused ? 'bold' : 'normal' }}>
72
        Messages
73
      </Text>
74
    ),
75
  }}
76
/>
77
```
78

79
### Tab Icon Configuration
80

81
Customize tab icons with full control over appearance and behavior.
82

83
```typescript { .api }
84
interface TabIconOptions {
85
  /**
86
   * A function that returns a React.Node to display in the tab bar.
87
   */
88
  tabBarIcon?: (props: {
89
    focused: boolean;
90
    color: string;
91
    size: number;
92
  }) => React.ReactNode;
93
  
94
  /**
95
   * Style object for the tab icon.
96
   */
97
  tabBarIconStyle?: StyleProp<TextStyle>;
98
}
99
```
100

101
**Usage Examples:**
102

103
```typescript
104
import Icon from 'react-native-vector-icons/Ionicons';
105

106
<Tab.Screen
107
  name="Home"
108
  component={HomeScreen}
109
  options={{
110
    tabBarIcon: ({ focused, color, size }) => (
111
      <Icon 
112
        name={focused ? 'home' : 'home-outline'} 
113
        size={size} 
114
        color={color} 
115
      />
116
    ),
117
    tabBarIconStyle: {
118
      marginTop: 2,
119
    },
120
  }}
121
/>
122
```
123

124
### Tab Badge System
125

126
Display badges on tabs for notifications and status indicators.
127

128
```typescript { .api }
129
interface TabBadgeOptions {
130
  /**
131
   * Text to show in a badge on the tab icon.
132
   */
133
  tabBarBadge?: number | string;
134
  
135
  /**
136
   * Custom style for the tab bar badge.
137
   * You can specify a background color or text color here.
138
   */
139
  tabBarBadgeStyle?: StyleProp<TextStyle>;
140
}
141
```
142

143
**Usage Examples:**
144

145
```typescript
146
<Tab.Screen
147
  name="Messages"
148
  component={MessagesScreen}
149
  options={{
150
    tabBarBadge: 5,
151
    tabBarBadgeStyle: {
152
      backgroundColor: 'red',
153
      color: 'white',
154
    },
155
  }}
156
/>
157

158
// Dynamic badge
159
<Tab.Screen
160
  name="Notifications"
161
  component={NotificationsScreen}
162
  options={({ route }) => ({
163
    tabBarBadge: route.params?.unreadCount > 0 ? route.params.unreadCount : undefined,
164
  })}
165
/>
166
```
167

168
### Tab Colors and Appearance
169

170
Control the visual appearance of tabs including colors and backgrounds.
171

172
```typescript { .api }
173
interface TabAppearanceOptions {
174
  /**
175
   * Color for the icon and label in the active tab.
176
   */
177
  tabBarActiveTintColor?: string;
178
  
179
  /**
180
   * Color for the icon and label in the inactive tabs.
181
   */
182
  tabBarInactiveTintColor?: string;
183
  
184
  /**
185
   * Background color for the active tab.
186
   */
187
  tabBarActiveBackgroundColor?: string;
188
  
189
  /**
190
   * Background color for the inactive tabs.
191
   */
192
  tabBarInactiveBackgroundColor?: string;
193
  
194
  /**
195
   * Style object for the tab item container.
196
   */
197
  tabBarItemStyle?: StyleProp<ViewStyle>;
198
  
199
  /**
200
   * Variant of the tab bar. Defaults to `uikit`.
201
   */
202
  tabBarVariant?: Variant;
203
}
204

205
type Variant = 'uikit' | 'material';
206
```
207

208
**Usage Examples:**
209

210
```typescript
211
<Tab.Navigator
212
  screenOptions={{
213
    tabBarActiveTintColor: '#e91e63',
214
    tabBarInactiveTintColor: 'gray',
215
    tabBarActiveBackgroundColor: '#f0f0f0',
216
    tabBarItemStyle: {
217
      paddingVertical: 8,
218
    },
219
    tabBarVariant: 'material',
220
  }}
221
>
222
  {/* screens */}
223
</Tab.Navigator>
224
```
225

226
### Tab Bar Styling
227

228
Comprehensive styling options for the entire tab bar.
229

230
```typescript { .api }
231
interface TabBarStylingOptions {
232
  /**
233
   * Style object for the tab bar container.
234
   */
235
  tabBarStyle?: Animated.WithAnimatedValue<StyleProp<ViewStyle>>;
236
  
237
  /**
238
   * Function which returns a React Element to use as background for the tab bar.
239
   * When using `BlurView`, make sure to set `position: 'absolute'` in `tabBarStyle`.
240
   */
241
  tabBarBackground?: () => React.ReactNode;
242
  
243
  /**
244
   * Position of the tab bar on the screen. Defaults to `bottom`.
245
   */
246
  tabBarPosition?: 'bottom' | 'left' | 'right' | 'top';
247
}
248
```
249

250
**Usage Examples:**
251

252
```typescript
253
import { BlurView } from '@react-native-community/blur';
254

255
<Tab.Navigator
256
  screenOptions={{
257
    tabBarStyle: {
258
      position: 'absolute',
259
      backgroundColor: 'transparent',
260
      borderTopWidth: 0,
261
      elevation: 0,
262
    },
263
    tabBarBackground: () => (
264
      <BlurView
265
        style={{ ...StyleSheet.absoluteFillObject }}
266
        blurType="light"
267
        blurAmount={10}
268
      />
269
    ),
270
    tabBarPosition: 'bottom',
271
  }}
272
>
273
  {/* screens */}
274
</Tab.Navigator>
275
```
276

277
### Custom Tab Buttons
278

279
Replace default tab buttons with completely custom components.
280

281
```typescript { .api }
282
interface TabButtonOptions {
283
  /**
284
   * Function which returns a React element to render as the tab bar button.
285
   * Renders `PlatformPressable` by default.
286
   */
287
  tabBarButton?: (props: BottomTabBarButtonProps) => React.ReactNode;
288
}
289

290
interface BottomTabBarButtonProps extends Omit<
291
  React.ComponentProps<typeof PlatformPressable>,
292
  'style'
293
> {
294
  href?: string;
295
  children: React.ReactNode;
296
  style?: StyleProp<ViewStyle>;
297
  onPress?: (
298
    e: React.MouseEvent<HTMLAnchorElement, MouseEvent> | GestureResponderEvent
299
  ) => void;
300
}
301
```
302

303
**Usage Examples:**
304

305
```typescript
306
import { Pressable } from 'react-native';
307

308
<Tab.Screen
309
  name="Special"
310
  component={SpecialScreen}
311
  options={{
312
    tabBarButton: (props) => (
313
      <Pressable
314
        {...props}
315
        style={[
316
          props.style,
317
          {
318
            backgroundColor: 'purple',
319
            borderRadius: 25,
320
            margin: 5,
321
          }
322
        ]}
323
      />
324
    ),
325
  }}
326
/>
327
```
328

329
### Keyboard Interaction
330

331
Configure tab bar behavior when the keyboard is displayed.
332

333
```typescript { .api }
334
interface KeyboardInteractionOptions {
335
  /**
336
   * Whether the tab bar gets hidden when the keyboard is shown. Defaults to `false`.
337
   */
338
  tabBarHideOnKeyboard?: boolean;
339
  
340
  /**
341
   * Animation config for showing and hiding the tab bar when the keyboard is shown/hidden.
342
   */
343
  tabBarVisibilityAnimationConfig?: {
344
    show?: TabBarVisibilityAnimationConfig;
345
    hide?: TabBarVisibilityAnimationConfig;
346
  };
347
}
348

349
type TabBarVisibilityAnimationConfig = 
350
  | TimingKeyboardAnimationConfig 
351
  | SpringKeyboardAnimationConfig;
352

353
interface TimingKeyboardAnimationConfig {
354
  animation: 'timing';
355
  config?: Omit<
356
    Partial<Animated.TimingAnimationConfig>,
357
    'toValue' | 'useNativeDriver'
358
  >;
359
}
360

361
interface SpringKeyboardAnimationConfig {
362
  animation: 'spring';
363
  config?: Omit<
364
    Partial<Animated.SpringAnimationConfig>,
365
    'toValue' | 'useNativeDriver'
366
  >;
367
}
368
```
369

370
**Usage Examples:**
371

372
```typescript
373
<Tab.Navigator
374
  screenOptions={{
375
    tabBarHideOnKeyboard: true,
376
    tabBarVisibilityAnimationConfig: {
377
      show: {
378
        animation: 'spring',
379
        config: {
380
          damping: 15,
381
          stiffness: 150,
382
        },
383
      },
384
      hide: {
385
        animation: 'timing',
386
        config: {
387
          duration: 200,
388
        },
389
      },
390
    },
391
  }}
392
>
393
  {/* screens */}
394
</Tab.Navigator>
395
```
396

397
### Accessibility
398

399
Accessibility features for screen readers and assistive technologies.
400

401
```typescript { .api }
402
interface AccessibilityOptions {
403
  /**
404
   * Accessibility label for the tab button. This is read by the screen reader when the user taps the tab.
405
   * It's recommended to set this if you don't have a label for the tab.
406
   */
407
  tabBarAccessibilityLabel?: string;
408
  
409
  /**
410
   * ID to locate this tab button in tests.
411
   */
412
  tabBarButtonTestID?: string;
413
}
414
```
415

416
**Usage Examples:**
417

418
```typescript
419
<Tab.Screen
420
  name="Home"
421
  component={HomeScreen}
422
  options={{
423
    tabBarAccessibilityLabel: 'Home tab, double tap to navigate to home screen',
424
    tabBarButtonTestID: 'home-tab-button',
425
  }}
426
/>
427
```
428

429
## Complete Tab Bar Component
430

431
For advanced customization, you can replace the entire tab bar component.
432

433
```typescript { .api }
434
interface BottomTabBarProps {
435
  state: TabNavigationState<ParamListBase>;
436
  descriptors: BottomTabDescriptorMap;
437
  navigation: NavigationHelpers<ParamListBase, BottomTabNavigationEventMap>;
438
  insets: EdgeInsets;
439
}
440

441
const BottomTabBar: React.ComponentType<BottomTabBarProps & {
442
  style?: Animated.WithAnimatedValue<StyleProp<ViewStyle>>;
443
}>;
444
```
445

446
**Usage Examples:**
447

448
```typescript
449
import { BottomTabBar } from '@react-navigation/bottom-tabs';
450

451
function CustomTabBar(props) {
452
  return (
453
    <View>
454
      <BottomTabBar {...props} />
455
      <View style={{ height: 20, backgroundColor: 'blue' }} />
456
    </View>
457
  );
458
}
459

460
<Tab.Navigator tabBar={(props) => <CustomTabBar {...props} />}>
461
  {/* screens */}
462
</Tab.Navigator>
463
```