@react-navigation/bottom-tabs 7.10.1 → 8.0.0-alpha.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (139) hide show
  1. package/lib/module/index.js +3 -2
  2. package/lib/module/index.js.map +1 -1
  3. package/lib/module/navigators/createBottomTabNavigator.js +27 -9
  4. package/lib/module/navigators/createBottomTabNavigator.js.map +1 -1
  5. package/lib/module/utils/BottomTabAnimationContext.js +5 -0
  6. package/lib/module/utils/BottomTabAnimationContext.js.map +1 -0
  7. package/lib/module/utils/useBottomTabAnimation.js +12 -0
  8. package/lib/module/utils/useBottomTabAnimation.js.map +1 -0
  9. package/lib/module/utils/useTabBarPosition.js +34 -0
  10. package/lib/module/utils/useTabBarPosition.js.map +1 -0
  11. package/lib/module/views/BottomTabBar.js +46 -49
  12. package/lib/module/views/BottomTabBar.js.map +1 -1
  13. package/lib/module/views/BottomTabItem.js +17 -15
  14. package/lib/module/views/BottomTabItem.js.map +1 -1
  15. package/lib/module/views/BottomTabViewCommon.js +16 -0
  16. package/lib/module/views/BottomTabViewCommon.js.map +1 -0
  17. package/lib/module/views/{BottomTabView.js → BottomTabViewCustom.js} +107 -106
  18. package/lib/module/views/BottomTabViewCustom.js.map +1 -0
  19. package/lib/module/views/BottomTabViewNative.android.js +4 -0
  20. package/lib/module/views/BottomTabViewNative.android.js.map +1 -0
  21. package/lib/module/views/BottomTabViewNative.ios.js +4 -0
  22. package/lib/module/views/BottomTabViewNative.ios.js.map +1 -0
  23. package/lib/module/views/BottomTabViewNative.js +5 -0
  24. package/lib/module/views/BottomTabViewNative.js.map +1 -0
  25. package/lib/module/{unstable/NativeBottomTabView.native.js → views/BottomTabViewNativeImpl.js} +103 -80
  26. package/lib/module/views/BottomTabViewNativeImpl.js.map +1 -0
  27. package/lib/module/views/ScreenContent.js +39 -0
  28. package/lib/module/views/ScreenContent.js.map +1 -0
  29. package/lib/module/views/TabBarIcon.js +62 -4
  30. package/lib/module/views/TabBarIcon.js.map +1 -1
  31. package/lib/typescript/src/index.d.ts +4 -3
  32. package/lib/typescript/src/index.d.ts.map +1 -1
  33. package/lib/typescript/src/navigators/createBottomTabNavigator.d.ts +10 -6
  34. package/lib/typescript/src/navigators/createBottomTabNavigator.d.ts.map +1 -1
  35. package/lib/typescript/src/types.d.ts +392 -114
  36. package/lib/typescript/src/types.d.ts.map +1 -1
  37. package/lib/typescript/src/utils/BottomTabAnimationContext.d.ts +4 -0
  38. package/lib/typescript/src/utils/BottomTabAnimationContext.d.ts.map +1 -0
  39. package/lib/typescript/src/utils/useBottomTabAnimation.d.ts +2 -0
  40. package/lib/typescript/src/utils/useBottomTabAnimation.d.ts.map +1 -0
  41. package/lib/typescript/src/utils/useTabBarPosition.d.ts +3 -0
  42. package/lib/typescript/src/utils/useTabBarPosition.d.ts.map +1 -0
  43. package/lib/typescript/src/views/BottomTabBar.d.ts +4 -4
  44. package/lib/typescript/src/views/BottomTabBar.d.ts.map +1 -1
  45. package/lib/typescript/src/views/BottomTabItem.d.ts +16 -14
  46. package/lib/typescript/src/views/BottomTabItem.d.ts.map +1 -1
  47. package/lib/typescript/src/views/{BottomTabView.d.ts → BottomTabViewCommon.d.ts} +2 -2
  48. package/lib/typescript/src/views/BottomTabViewCommon.d.ts.map +1 -0
  49. package/lib/typescript/src/views/BottomTabViewCustom.d.ts +10 -0
  50. package/lib/typescript/src/views/BottomTabViewCustom.d.ts.map +1 -0
  51. package/lib/typescript/src/views/BottomTabViewNative.android.d.ts +2 -0
  52. package/lib/typescript/src/views/BottomTabViewNative.android.d.ts.map +1 -0
  53. package/lib/typescript/src/views/BottomTabViewNative.d.ts +3 -0
  54. package/lib/typescript/src/views/BottomTabViewNative.d.ts.map +1 -0
  55. package/lib/typescript/src/views/BottomTabViewNative.ios.d.ts +2 -0
  56. package/lib/typescript/src/views/BottomTabViewNative.ios.d.ts.map +1 -0
  57. package/lib/typescript/src/views/BottomTabViewNativeImpl.d.ts +10 -0
  58. package/lib/typescript/src/views/BottomTabViewNativeImpl.d.ts.map +1 -0
  59. package/lib/typescript/src/views/ScreenContent.d.ts +13 -0
  60. package/lib/typescript/src/views/ScreenContent.d.ts.map +1 -0
  61. package/lib/typescript/src/views/TabBarIcon.d.ts +10 -10
  62. package/lib/typescript/src/views/TabBarIcon.d.ts.map +1 -1
  63. package/package.json +12 -17
  64. package/src/index.tsx +7 -2
  65. package/src/navigators/createBottomTabNavigator.tsx +78 -27
  66. package/src/types.tsx +425 -122
  67. package/src/utils/BottomTabAnimationContext.tsx +7 -0
  68. package/src/utils/useBottomTabAnimation.tsx +15 -0
  69. package/src/utils/useTabBarPosition.tsx +41 -0
  70. package/src/views/BottomTabBar.tsx +68 -67
  71. package/src/views/BottomTabItem.tsx +39 -34
  72. package/src/views/BottomTabViewCommon.tsx +26 -0
  73. package/src/views/{BottomTabView.tsx → BottomTabViewCustom.tsx} +142 -129
  74. package/src/views/BottomTabViewNative.android.tsx +1 -0
  75. package/src/views/BottomTabViewNative.ios.tsx +1 -0
  76. package/src/views/BottomTabViewNative.tsx +3 -0
  77. package/src/{unstable/NativeBottomTabView.native.tsx → views/BottomTabViewNativeImpl.tsx} +161 -120
  78. package/src/views/ScreenContent.tsx +58 -0
  79. package/src/views/TabBarIcon.tsx +79 -11
  80. package/lib/module/unstable/NativeBottomTabView.js +0 -6
  81. package/lib/module/unstable/NativeBottomTabView.js.map +0 -1
  82. package/lib/module/unstable/NativeBottomTabView.native.js.map +0 -1
  83. package/lib/module/unstable/NativeScreen/NativeScreen.js +0 -152
  84. package/lib/module/unstable/NativeScreen/NativeScreen.js.map +0 -1
  85. package/lib/module/unstable/NativeScreen/debounce.js +0 -12
  86. package/lib/module/unstable/NativeScreen/debounce.js.map +0 -1
  87. package/lib/module/unstable/NativeScreen/types.js +0 -4
  88. package/lib/module/unstable/NativeScreen/types.js.map +0 -1
  89. package/lib/module/unstable/NativeScreen/useAnimatedHeaderHeight.js +0 -12
  90. package/lib/module/unstable/NativeScreen/useAnimatedHeaderHeight.js.map +0 -1
  91. package/lib/module/unstable/NativeScreen/useHeaderConfig.js +0 -304
  92. package/lib/module/unstable/NativeScreen/useHeaderConfig.js.map +0 -1
  93. package/lib/module/unstable/createNativeBottomTabNavigator.js +0 -6
  94. package/lib/module/unstable/createNativeBottomTabNavigator.js.map +0 -1
  95. package/lib/module/unstable/createNativeBottomTabNavigator.native.js +0 -65
  96. package/lib/module/unstable/createNativeBottomTabNavigator.native.js.map +0 -1
  97. package/lib/module/unstable/index.js +0 -16
  98. package/lib/module/unstable/index.js.map +0 -1
  99. package/lib/module/unstable/types.js +0 -4
  100. package/lib/module/unstable/types.js.map +0 -1
  101. package/lib/module/views/BottomTabView.js.map +0 -1
  102. package/lib/module/views/ScreenFallback.js +0 -42
  103. package/lib/module/views/ScreenFallback.js.map +0 -1
  104. package/lib/typescript/src/unstable/NativeBottomTabView.d.ts +0 -10
  105. package/lib/typescript/src/unstable/NativeBottomTabView.d.ts.map +0 -1
  106. package/lib/typescript/src/unstable/NativeBottomTabView.native.d.ts +0 -10
  107. package/lib/typescript/src/unstable/NativeBottomTabView.native.d.ts.map +0 -1
  108. package/lib/typescript/src/unstable/NativeScreen/NativeScreen.d.ts +0 -8
  109. package/lib/typescript/src/unstable/NativeScreen/NativeScreen.d.ts.map +0 -1
  110. package/lib/typescript/src/unstable/NativeScreen/debounce.d.ts +0 -2
  111. package/lib/typescript/src/unstable/NativeScreen/debounce.d.ts.map +0 -1
  112. package/lib/typescript/src/unstable/NativeScreen/types.d.ts +0 -523
  113. package/lib/typescript/src/unstable/NativeScreen/types.d.ts.map +0 -1
  114. package/lib/typescript/src/unstable/NativeScreen/useAnimatedHeaderHeight.d.ts +0 -5
  115. package/lib/typescript/src/unstable/NativeScreen/useAnimatedHeaderHeight.d.ts.map +0 -1
  116. package/lib/typescript/src/unstable/NativeScreen/useHeaderConfig.d.ts +0 -11
  117. package/lib/typescript/src/unstable/NativeScreen/useHeaderConfig.d.ts.map +0 -1
  118. package/lib/typescript/src/unstable/createNativeBottomTabNavigator.d.ts +0 -2
  119. package/lib/typescript/src/unstable/createNativeBottomTabNavigator.d.ts.map +0 -1
  120. package/lib/typescript/src/unstable/createNativeBottomTabNavigator.native.d.ts +0 -16
  121. package/lib/typescript/src/unstable/createNativeBottomTabNavigator.native.d.ts.map +0 -1
  122. package/lib/typescript/src/unstable/index.d.ts +0 -13
  123. package/lib/typescript/src/unstable/index.d.ts.map +0 -1
  124. package/lib/typescript/src/unstable/types.d.ts +0 -319
  125. package/lib/typescript/src/unstable/types.d.ts.map +0 -1
  126. package/lib/typescript/src/views/BottomTabView.d.ts.map +0 -1
  127. package/lib/typescript/src/views/ScreenFallback.d.ts +0 -18
  128. package/lib/typescript/src/views/ScreenFallback.d.ts.map +0 -1
  129. package/src/unstable/NativeBottomTabView.tsx +0 -20
  130. package/src/unstable/NativeScreen/NativeScreen.tsx +0 -212
  131. package/src/unstable/NativeScreen/debounce.tsx +0 -14
  132. package/src/unstable/NativeScreen/types.ts +0 -573
  133. package/src/unstable/NativeScreen/useAnimatedHeaderHeight.tsx +0 -18
  134. package/src/unstable/NativeScreen/useHeaderConfig.tsx +0 -434
  135. package/src/unstable/createNativeBottomTabNavigator.native.tsx +0 -116
  136. package/src/unstable/createNativeBottomTabNavigator.tsx +0 -4
  137. package/src/unstable/index.tsx +0 -23
  138. package/src/unstable/types.tsx +0 -403
  139. package/src/views/ScreenFallback.tsx +0 -50
package/src/types.tsx CHANGED
@@ -17,24 +17,33 @@ import type {
17
17
  import type * as React from 'react';
18
18
  import type {
19
19
  Animated,
20
+ ColorValue,
20
21
  GestureResponderEvent,
22
+ ImageSourcePropType,
21
23
  StyleProp,
22
24
  TextStyle,
23
25
  ViewStyle,
24
26
  } from 'react-native';
25
- import type { EdgeInsets } from 'react-native-safe-area-context';
26
-
27
- export type Layout = { width: number; height: number };
27
+ import type {
28
+ TabBarItemLabelVisibilityMode,
29
+ TabsScreenBlurEffect,
30
+ TabsSystemItem,
31
+ } from 'react-native-screens';
32
+ import type { SFSymbol } from 'sf-symbols-typescript';
28
33
 
29
34
  export type Variant = 'uikit' | 'material';
30
35
 
31
36
  export type BottomTabNavigationEventMap = {
32
37
  /**
33
38
  * Event which fires on tapping on the tab in the tab bar.
39
+ *
40
+ * Preventing default is only supported with `custom` implementation.
34
41
  */
35
42
  tabPress: { data: undefined; canPreventDefault: true };
36
43
  /**
37
44
  * Event which fires on long press on the tab in the tab bar.
45
+ *
46
+ * Only supported with `custom` implementation.
38
47
  */
39
48
  tabLongPress: { data: undefined };
40
49
  /**
@@ -58,31 +67,27 @@ export type BottomTabNavigationHelpers = NavigationHelpers<
58
67
  export type BottomTabNavigationProp<
59
68
  ParamList extends ParamListBase,
60
69
  RouteName extends keyof ParamList = keyof ParamList,
61
- NavigatorID extends string | undefined = undefined,
62
70
  > = NavigationProp<
63
71
  ParamList,
64
72
  RouteName,
65
- NavigatorID,
66
73
  TabNavigationState<ParamList>,
67
74
  BottomTabNavigationOptions,
68
- BottomTabNavigationEventMap
69
- > &
70
- TabActionHelpers<ParamList>;
75
+ BottomTabNavigationEventMap,
76
+ TabActionHelpers<ParamList>
77
+ >;
71
78
 
72
79
  export type BottomTabScreenProps<
73
80
  ParamList extends ParamListBase,
74
81
  RouteName extends keyof ParamList = keyof ParamList,
75
- NavigatorID extends string | undefined = undefined,
76
82
  > = {
77
- navigation: BottomTabNavigationProp<ParamList, RouteName, NavigatorID>;
83
+ navigation: BottomTabNavigationProp<ParamList, RouteName>;
78
84
  route: RouteProp<ParamList, RouteName>;
79
85
  };
80
86
 
81
87
  export type BottomTabOptionsArgs<
82
88
  ParamList extends ParamListBase,
83
89
  RouteName extends keyof ParamList = keyof ParamList,
84
- NavigatorID extends string | undefined = undefined,
85
- > = BottomTabScreenProps<ParamList, RouteName, NavigatorID> & {
90
+ > = BottomTabScreenProps<ParamList, RouteName> & {
86
91
  theme: Theme;
87
92
  };
88
93
 
@@ -108,31 +113,92 @@ export type TabBarVisibilityAnimationConfig =
108
113
 
109
114
  export type TabAnimationName = 'none' | 'fade' | 'shift';
110
115
 
111
- export type BottomTabNavigationOptions = HeaderOptions & {
116
+ type IconImage = {
112
117
  /**
113
- * Title text for the screen.
118
+ * - `image` - Use a local image as the icon.
114
119
  */
115
- title?: string;
120
+ type: 'image';
121
+ /**
122
+ * Image source to use as the icon.
123
+ * e.g., `require('./path/to/image.png')`
124
+ */
125
+ source: ImageSourcePropType;
126
+ /**
127
+ * Whether to apply tint color to the icon.
128
+ * Defaults to `true`.
129
+ *
130
+ * @platform ios
131
+ */
132
+ tinted?: boolean;
133
+ };
116
134
 
135
+ type IconIOSSfSymbol = {
136
+ /**
137
+ * - `sfSymbol` - Use an SF Symbol as the icon on iOS.
138
+ */
139
+ type: 'sfSymbol';
117
140
  /**
118
- * Title string of a tab displayed in the tab bar
119
- * or a function that given { focused: boolean, color: string, position: 'below-icon' | 'beside-icon', children: string } returns a React.Node to display in tab bar.
141
+ * Name of the SF Symbol to use as the icon.
120
142
  *
121
- * When undefined, scene title is used. Use `tabBarShowLabel` to hide the label.
143
+ * @platform ios
122
144
  */
123
- tabBarLabel?:
124
- | string
125
- | ((props: {
126
- focused: boolean;
127
- color: string;
128
- position: LabelPosition;
129
- children: string;
130
- }) => React.ReactNode);
145
+ name: SFSymbol;
146
+ };
131
147
 
148
+ type IconAndroidDrawable = {
149
+ /**
150
+ * - `drawableResource` - Use a drawable resource as the icon on Android.
151
+ */
152
+ type: 'drawableResource';
153
+ /**
154
+ * Name of the drawable resource to use as the icon.
155
+ *
156
+ * @platform android
157
+ */
158
+ name: string;
132
159
  /**
133
- * Whether the tab label should be visible. Defaults to `true`.
160
+ * Whether to apply tint color to the icon.
161
+ * Only supported with custom implementation.
162
+ *
163
+ * Defaults to `true`.
164
+ *
165
+ * @platform android
134
166
  */
135
- tabBarShowLabel?: boolean;
167
+ tinted?: boolean;
168
+ };
169
+
170
+ type IconIOS = IconIOSSfSymbol | IconImage;
171
+
172
+ type IconAndroid = IconAndroidDrawable | IconImage;
173
+
174
+ export type BottomTabIcon = IconIOS | IconAndroid;
175
+
176
+ type BottomTabCustomOptions = {
177
+ /**
178
+ * How the screen should animate when switching tabs.
179
+ *
180
+ * Supported values:
181
+ * - 'none': don't animate the screen (default)
182
+ * - 'fade': cross-fade the screens.
183
+ * - 'shift': shift the screens slightly shift to left/right.
184
+ *
185
+ * Only supported with `custom` implementation.
186
+ */
187
+ animation?: TabAnimationName;
188
+
189
+ /**
190
+ * Function which specifies interpolated styles for bottom-tab scenes.
191
+ *
192
+ * Only supported with `custom` implementation.
193
+ */
194
+ sceneStyleInterpolator?: BottomTabSceneStyleInterpolator;
195
+
196
+ /**
197
+ * Object which specifies the animation type (timing or spring) and their options (such as duration for timing).
198
+ *
199
+ * Only supported with `custom` implementation.
200
+ */
201
+ transitionSpec?: TransitionSpec;
136
202
 
137
203
  /**
138
204
  * Whether the label is shown below the icon or beside the icon.
@@ -141,180 +207,416 @@ export type BottomTabNavigationOptions = HeaderOptions & {
141
207
  * - `beside-icon` the label is shown next to the icon (typical for iPad)
142
208
  *
143
209
  * By default, the position is chosen automatically based on device width.
210
+ *
211
+ * Only supported with `custom` implementation.
144
212
  */
145
213
  tabBarLabelPosition?: LabelPosition;
146
214
 
147
215
  /**
148
- * Style object for the tab label.
216
+ * Whether label font should scale to respect Text Size accessibility settings.
217
+ *
218
+ * Defaults to `true`.
219
+ *
220
+ * Only supported with `custom` implementation.
149
221
  */
150
- tabBarLabelStyle?: StyleProp<TextStyle>;
222
+ tabBarAllowFontScaling?: boolean;
151
223
 
152
224
  /**
153
- * Whether label font should scale to respect Text Size accessibility settings.
225
+ * Accessibility label for the tab button. This is read by the screen reader when the user taps the tab.
226
+ * It's recommended to set this if you don't have a label for the tab.
227
+ *
228
+ * Only supported with `custom` implementation.
154
229
  */
155
- tabBarAllowFontScaling?: boolean;
230
+ tabBarAccessibilityLabel?: string;
156
231
 
157
232
  /**
158
- * A function that given { focused: boolean, color: string } returns a React.Node to display in the tab bar.
233
+ * ID to locate this tab button in tests.
234
+ *
235
+ * Only supported with `custom` implementation.
159
236
  */
160
- tabBarIcon?: (props: {
161
- focused: boolean;
162
- color: string;
163
- size: number;
164
- }) => React.ReactNode;
237
+ tabBarButtonTestID?: string;
238
+
239
+ /**
240
+ * Style object for the tab item container.
241
+ *
242
+ * Only supported with `custom` implementation.
243
+ */
244
+ tabBarItemStyle?: StyleProp<ViewStyle>;
165
245
 
166
246
  /**
167
247
  * Style object for the tab icon.
248
+ *
249
+ * Only supported with `custom` implementation.
168
250
  */
169
251
  tabBarIconStyle?: StyleProp<TextStyle>;
170
252
 
171
253
  /**
172
- * Text to show in a badge on the tab icon.
254
+ * Whether the tab bar gets hidden when the keyboard is shown.
255
+ *
256
+ * Defaults to `false`.
257
+ *
258
+ * Only supported with `custom` implementation.
173
259
  */
174
- tabBarBadge?: number | string;
260
+ tabBarHideOnKeyboard?: boolean;
175
261
 
176
262
  /**
177
- * Custom style for the tab bar badge.
178
- * You can specify a background color or text color here.
263
+ * Animation config for showing and hiding the tab bar when the keyboard is shown/hidden.
264
+ *
265
+ * Only supported with `custom` implementation.
179
266
  */
180
- tabBarBadgeStyle?: StyleProp<TextStyle>;
267
+ tabBarVisibilityAnimationConfig?: {
268
+ show?: TabBarVisibilityAnimationConfig;
269
+ hide?: TabBarVisibilityAnimationConfig;
270
+ };
181
271
 
182
272
  /**
183
- * Accessibility label for the tab button. This is read by the screen reader when the user taps the tab.
184
- * It's recommended to set this if you don't have a label for the tab.
273
+ * Variant of the tab bar. Defaults to `uikit`.
274
+ *
275
+ * Only supported with `custom` implementation.
185
276
  */
186
- tabBarAccessibilityLabel?: string;
277
+ tabBarVariant?: Variant;
187
278
 
188
279
  /**
189
- * ID to locate this tab button in tests.
280
+ * Style object for the tab bar container.
281
+ *
282
+ * Only supported with `custom` implementation.
190
283
  */
191
- tabBarButtonTestID?: string;
284
+ tabBarStyle?: Animated.WithAnimatedValue<StyleProp<ViewStyle>>;
285
+
286
+ /**
287
+ * Function which returns a React Element to use as background for the tab bar.
288
+ * You could render an image, a gradient, blur view etc.
289
+ *
290
+ * When using `BlurView`, make sure to set `position: 'absolute'` in `tabBarStyle` as well.
291
+ * You'd also need to use `useBottomTabBarHeight()` to add a bottom padding to your content.
292
+ *
293
+ * Only supported with `custom` implementation.
294
+ */
295
+ tabBarBackground?: () => React.ReactNode;
296
+
297
+ /**
298
+ * Position of the tab bar on the screen. Defaults to `bottom`.
299
+ *
300
+ * Only supported with `custom` implementation or if custom tab bar is provided.
301
+ */
302
+ tabBarPosition?: 'bottom' | 'left' | 'right' | 'top';
303
+
304
+ /**
305
+ * Background color for the active tab.
306
+ *
307
+ * Only supported with `custom` implementation.
308
+ */
309
+ tabBarActiveBackgroundColor?: ColorValue;
310
+
311
+ /**
312
+ * Background color for the inactive tabs.
313
+ *
314
+ * Only supported with `custom` implementation.
315
+ */
316
+ tabBarInactiveBackgroundColor?: ColorValue;
192
317
 
193
318
  /**
194
319
  * Function which returns a React element to render as the tab bar button.
195
320
  * Renders `PlatformPressable` by default.
321
+ *
322
+ * Only supported with `custom` implementation.
196
323
  */
197
324
  tabBarButton?: (props: BottomTabBarButtonProps) => React.ReactNode;
325
+ };
326
+
327
+ type ScrollEdgeEffect = 'auto' | 'hard' | 'soft' | 'hidden';
198
328
 
329
+ type BottomTabNativeOptions = {
199
330
  /**
200
- * Color for the icon and label in the active tab.
331
+ * Uses iOS built-in tab bar items with standard iOS styling and localized titles.
332
+ * If set to `search`, it's positioned next to the tab bar on iOS 26 and above.
333
+ *
334
+ * The `tabBarIcon` and `tabBarLabel` options will override the icon and label from the system item.
335
+ * If you want to keep the system behavior on iOS, but need to provide icon and label for other platforms,
336
+ * Use `Platform.OS` or `Platform.select` to conditionally set `undefined` for `tabBarIcon` and `tabBarLabel` on iOS.
337
+ *
338
+ * @platform ios
201
339
  */
202
- tabBarActiveTintColor?: string;
340
+ tabBarSystemItem?: TabsSystemItem;
203
341
 
204
342
  /**
205
- * Color for the icon and label in the inactive tabs.
343
+ * Blur effect applied to the tab bar when tab screen is selected.
344
+ *
345
+ * Works with backgroundColor's alpha < 1.
346
+ *
347
+ * The following values are currently supported:
348
+ *
349
+ * - `none` - disables blur effect
350
+ * - `systemDefault` - uses UIKit's default tab bar blur effect
351
+ * - one of styles mapped from UIKit's UIBlurEffectStyle, e.g. `systemUltraThinMaterial`
352
+ *
353
+ * Defaults to `systemDefault`.
354
+ *
355
+ * Complete list of possible blur effect styles is available in the official UIKit documentation:
356
+ * @see {@link https://developer.apple.com/documentation/uikit/uiblureffect/style|UIBlurEffect.Style}
357
+ *
358
+ * Only supported on iOS 18 and lower.
359
+ *
360
+ * @platform ios
206
361
  */
207
- tabBarInactiveTintColor?: string;
362
+ tabBarBlurEffect?: TabsScreenBlurEffect;
208
363
 
209
364
  /**
210
- * Background color for the active tab.
365
+ * Minimize behavior for the tab bar.
366
+ *
367
+ * The following values are currently supported:
368
+ *
369
+ * - `auto` - resolves to the system default minimize behavior
370
+ * - `none` - the tab bar does not minimize
371
+ * - `onScrollDown` - the tab bar minimizes when scrolling down and
372
+ * expands when scrolling back up
373
+ * - `onScrollUp` - the tab bar minimizes when scrolling up and expands
374
+ * when scrolling back down
375
+ *
376
+ * Defaults to `auto`.
377
+ *
378
+ * The supported values correspond to the official UIKit documentation:
379
+ * @see {@link https://developer.apple.com/documentation/uikit/uitabbarcontroller/minimizebehavior|UITabBarController.MinimizeBehavior}
380
+ *
381
+ * Available starting from iOS 26.
382
+ *
383
+ * @platform ios
211
384
  */
212
- tabBarActiveBackgroundColor?: string;
385
+ tabBarMinimizeBehavior?: 'auto' | 'none' | 'onScrollDown' | 'onScrollUp';
213
386
 
214
387
  /**
215
- * Background color for the inactive tabs.
388
+ * Background color of the active indicator.
389
+ *
390
+ * Only supported with `native` implementation.
391
+ *
392
+ * @platform android
216
393
  */
217
- tabBarInactiveBackgroundColor?: string;
394
+ tabBarActiveIndicatorColor?: ColorValue;
218
395
 
219
396
  /**
220
- * Style object for the tab item container.
397
+ * Specifies if the active indicator should be used. Defaults to `true`.
398
+ *
399
+ * Only supported with `native` implementation.
400
+ *
401
+ * @platform android
221
402
  */
222
- tabBarItemStyle?: StyleProp<ViewStyle>;
403
+ tabBarActiveIndicatorEnabled?: boolean;
223
404
 
224
405
  /**
225
- * Whether the tab bar gets hidden when the keyboard is shown. Defaults to `false`.
406
+ * Function which returns a React element to display as an accessory view.
407
+ *
408
+ * Accepts a `placement` parameter which can be one of the following values:
409
+ * - `regular` - at bottom of the screen, above the tab bar if tab bar is at the bottom
410
+ * - `inline` - inline with the collapsed bottom tab bar (e.g. when minimized based on `tabBarMinimizeBehavior`)
411
+ *
412
+ * Note: the content is rendered twice for both placements, but only one is visible at a time based on the tab bar state.
413
+ * Any shared state should be stored outside of the component to keep both versions in sync.
414
+ *
415
+ * Available starting from iOS 26.
416
+ *
417
+ * Only supported with `native` implementation.
418
+ *
419
+ * @platform ios
226
420
  */
227
- tabBarHideOnKeyboard?: boolean;
421
+ bottomAccessory?: (options: {
422
+ placement: 'regular' | 'inline';
423
+ }) => React.ReactNode;
228
424
 
229
425
  /**
230
- * Animation config for showing and hiding the tab bar when the keyboard is shown/hidden.
426
+ * Configures the scroll edge effect for the _content ScrollView_ (the ScrollView that is present in first descendants chain of the Screen).
427
+ * Depending on values set, it will blur the scrolling content below certain UI elements (header items, search bar)
428
+ * for the specified edge of the ScrollView.
429
+ *
430
+ * When set in nested containers, i.e. Native Stack inside Native Bottom Tabs, or the other way around,
431
+ * the ScrollView will use only the innermost one's config.
432
+ *
433
+ * **Note:** Using both `headerBlurEffect` and `scrollEdgeEffects` (>= iOS 26) simultaneously may cause overlapping effects.
434
+ *
435
+ * Edge effects can be configured for each edge separately. The following values are currently supported:
436
+ *
437
+ * - `auto` - the automatic scroll edge effect style,
438
+ * - `hard` - a scroll edge effect with a hard cutoff and dividing line,
439
+ * - `soft` - a soft-edged scroll edge effect,
440
+ * - `hidden` - no scroll edge effect.
441
+ *
442
+ * Defaults to `automatic` for each edge.
443
+ *
444
+ * Available starting from iOS 26.
445
+ *
446
+ * Only supported with `native` implementation.
447
+ *
448
+ * @platform ios
231
449
  */
232
- tabBarVisibilityAnimationConfig?: {
233
- show?: TabBarVisibilityAnimationConfig;
234
- hide?: TabBarVisibilityAnimationConfig;
450
+ scrollEdgeEffects?: {
451
+ bottom?: ScrollEdgeEffect;
452
+ left?: ScrollEdgeEffect;
453
+ right?: ScrollEdgeEffect;
454
+ top?: ScrollEdgeEffect;
235
455
  };
456
+ };
236
457
 
458
+ export type BottomTabNavigationOptions = {
237
459
  /**
238
- * Variant of the tab bar. Defaults to `uikit`.
460
+ * Title text for the screen.
239
461
  */
240
- tabBarVariant?: Variant;
462
+ title?: string;
241
463
 
242
464
  /**
243
- * Style object for the tab bar container.
465
+ * Title string of the tab displayed in the tab bar
466
+ *
467
+ * Overrides the label provided by `tabBarSystemItem` on iOS.
468
+ *
469
+ * If not provided, or set to `undefined`:
470
+ * - The system values are used if `tabBarSystemItem` is set on iOS.
471
+ * - Otherwise, it falls back to the `title` or route name.
244
472
  */
245
- tabBarStyle?: Animated.WithAnimatedValue<StyleProp<ViewStyle>>;
473
+ tabBarLabel?: string;
246
474
 
247
475
  /**
248
- * Function which returns a React Element to use as background for the tab bar.
249
- * You could render an image, a gradient, blur view etc.
476
+ * Label visibility mode for the tab bar items.
250
477
  *
251
- * When using `BlurView`, make sure to set `position: 'absolute'` in `tabBarStyle` as well.
252
- * You'd also need to use `useBottomTabBarHeight()` to add a bottom padding to your content.
478
+ * The following values are currently supported:
479
+ *
480
+ * - `auto` - decided based on platform and implementation
481
+ * - `labeled` - labels are always shown
482
+ * - `unlabeled` - labels are never shown
483
+ * - `selected` - labels shown only for selected tab (only supported on Android with `native` implementation)
484
+ *
485
+ * Defaults to `auto`.
486
+ *
487
+ * Supported on all platforms with `custom` implementation.
488
+ * Only supported on Android with `native` implementation.
253
489
  */
254
- tabBarBackground?: () => React.ReactNode;
490
+ tabBarLabelVisibilityMode?: TabBarItemLabelVisibilityMode;
255
491
 
256
492
  /**
257
- * Position of the tab bar on the screen. Defaults to `bottom`.
493
+ * Style object for the tab label.
258
494
  */
259
- tabBarPosition?: 'bottom' | 'left' | 'right' | 'top';
495
+ tabBarLabelStyle?: Pick<
496
+ TextStyle,
497
+ 'fontFamily' | 'fontSize' | 'fontWeight' | 'fontStyle'
498
+ >;
260
499
 
261
500
  /**
262
- * Whether this screens should render the first time it's accessed. Defaults to `true`.
263
- * Set it to `false` if you want to render the screen on initial render.
501
+ * Icon to display for the tab.
502
+ *
503
+ * Overrides the icon provided by `tabBarSystemItem` on iOS with native implementation.
504
+ *
505
+ * Providing different icon for focused and unfocused states is supported:
506
+ * - on all platforms with `custom` implementation
507
+ * - on iOS with `native` implementation
508
+ *
509
+ * A React element is only supported with `custom` implementation.
264
510
  */
265
- lazy?: boolean;
511
+ tabBarIcon?:
512
+ | BottomTabIcon
513
+ | ((props: {
514
+ focused: boolean;
515
+ color: ColorValue;
516
+ size: number;
517
+ }) => BottomTabIcon | React.ReactNode);
266
518
 
267
519
  /**
268
- * Function that given returns a React Element to display as a header.
520
+ * Text to show in a badge on the tab icon.
269
521
  */
270
- header?: (props: BottomTabHeaderProps) => React.ReactNode;
522
+ tabBarBadge?: number | string;
271
523
 
272
524
  /**
273
- * Whether to show the header. Setting this to `false` hides the header.
274
- * Defaults to `true`.
525
+ * Custom style for the tab bar badge.
526
+ * You can specify a background color or text color here.
527
+ *
528
+ * @platform android
275
529
  */
276
- headerShown?: boolean;
530
+ tabBarBadgeStyle?: {
531
+ backgroundColor?: ColorValue;
532
+ color?: ColorValue;
533
+ };
277
534
 
278
535
  /**
279
- * Whether any nested stack should be popped to top when navigating away from the tab.
280
- * Defaults to `false`.
536
+ * Color for the icon and label in the active tab.
281
537
  */
282
- popToTopOnBlur?: boolean;
538
+ tabBarActiveTintColor?: ColorValue;
283
539
 
284
540
  /**
285
- * Whether inactive screens should be suspended from re-rendering. Defaults to `false`.
286
- * Defaults to `true` when `enableFreeze()` is run at the top of the application.
287
- * Requires `react-native-screens` version >=3.16.0.
288
- *
289
- * Only supported on iOS and Android.
541
+ * Color for the icon and label in the inactive tabs.
290
542
  */
291
- freezeOnBlur?: boolean;
543
+ tabBarInactiveTintColor?: ColorValue;
292
544
 
293
545
  /**
294
- * Style object for the component wrapping the screen content.
546
+ * Color of tab bar item's ripple effect.
547
+ *
548
+ * @platform android
295
549
  */
296
- sceneStyle?: StyleProp<ViewStyle>;
550
+ tabBarRippleColor?: ColorValue;
297
551
 
298
552
  /**
299
- * How the screen should animate when switching tabs.
553
+ * Display mode for the tab bar.
300
554
  *
301
555
  * Supported values:
302
- * - 'none': don't animate the screen (default)
303
- * - 'fade': cross-fade the screens.
304
- * - 'shift': shift the screens slightly shift to left/right.
556
+ * - `auto` - automatic based on the tab’s content
557
+ * - `tabBar` - tab items are shown in a traditional tab bar
558
+ * - `tabSidebar` - tab items are shown in a sidebar
559
+ *
560
+ * Supported on all platforms with `custom` implementation. By default:
561
+ * - `tabBar` is positioned at the bottom
562
+ * - `tabSidebar` is positioned on the left (LTR) or right (RTL)
563
+ *
564
+ * The `tabBarPosition` option can be used to override this in `custom` implementation.
565
+ *
566
+ * Supported on iOS 18 and above with `native` implementation.
567
+ * Not supported on tvOS.
305
568
  */
306
- animation?: TabAnimationName;
569
+ tabBarControllerMode?: 'auto' | 'tabBar' | 'tabSidebar';
307
570
 
308
571
  /**
309
- * Function which specifies interpolated styles for bottom-tab scenes.
572
+ * Style object for the tab bar container.
310
573
  */
311
- sceneStyleInterpolator?: BottomTabSceneStyleInterpolator;
574
+ tabBarStyle?: {
575
+ /**
576
+ * Background color of the tab bar.
577
+ *
578
+ * Only supported on Android and iOS 18 and below.
579
+ */
580
+ backgroundColor?: ColorValue;
581
+ /**
582
+ * Shadow color of the tab bar.
583
+ *
584
+ * Only supported on iOS 18 and below.
585
+ */
586
+ shadowColor?: ColorValue;
587
+ };
312
588
 
313
589
  /**
314
- * Object which specifies the animation type (timing or spring) and their options (such as duration for timing).
590
+ * Whether this screens should render the first time it's accessed. Defaults to `true`.
591
+ * Set it to `false` if you want to render the screen on initial render.
315
592
  */
316
- transitionSpec?: TransitionSpec;
317
- };
593
+ lazy?: boolean;
594
+
595
+ /**
596
+ * Whether any nested stack should be popped to top when navigating away from the tab.
597
+ * Defaults to `false`.
598
+ */
599
+ popToTopOnBlur?: boolean; // TODO: handle natively
600
+
601
+ /**
602
+ * Style object for the component wrapping the screen content.
603
+ */
604
+ sceneStyle?: StyleProp<ViewStyle>;
605
+
606
+ /**
607
+ * Function that returns a React Element to display as a header.
608
+ */
609
+ header?: (props: BottomTabHeaderProps) => React.ReactNode;
610
+
611
+ /**
612
+ * Whether to show the header.
613
+ *
614
+ * Defaults to `false` unless a header is provided.
615
+ */
616
+ headerShown?: boolean;
617
+ } & HeaderOptions &
618
+ BottomTabNativeOptions &
619
+ BottomTabCustomOptions;
318
620
 
319
621
  export type BottomTabDescriptor = Descriptor<
320
622
  BottomTabNavigationOptions,
@@ -385,32 +687,35 @@ export type BottomTabTransitionPreset = {
385
687
 
386
688
  export type BottomTabNavigationConfig = {
387
689
  /**
388
- * Function that returns a React element to display as the tab bar.
690
+ * The implementation to use for rendering the bottom tabs.
691
+ *
692
+ * - `native`: uses native platform bottom tabs on Android and iOS.
693
+ * - `custom`: uses a custom JavaScript implementation for all platforms.
694
+ *
695
+ * Some feature may not be available depending on the implementation used.
696
+ *
697
+ * Defaults to `native` on Android and iOS.
698
+ *
699
+ * On other platforms, it's always `custom` and this option has no effect.
389
700
  */
390
- tabBar?: (props: BottomTabBarProps) => React.ReactNode;
701
+ implementation?: 'native' | 'custom';
702
+
391
703
  /**
392
- * Safe area insets for the tab bar. This is used to avoid elements like the navigation bar on Android and bottom safe area on iOS.
393
- * By default, the device's safe area insets are automatically detected. You can override the behavior with this option.
704
+ * Function that returns a React element to display as the tab bar.
394
705
  */
395
- safeAreaInsets?: {
396
- top?: number;
397
- right?: number;
398
- bottom?: number;
399
- left?: number;
400
- };
706
+ tabBar?: (props: BottomTabBarProps) => React.ReactNode;
707
+
401
708
  /**
402
709
  * Whether inactive screens should be detached from the view hierarchy to save memory.
403
- * Make sure to call `enableScreens` from `react-native-screens` to make it work.
404
- * Defaults to `true` on Android.
710
+ *
711
+ * Defaults to `true`.
712
+ *
713
+ * Only supported with `custom` implementation.
405
714
  */
406
715
  detachInactiveScreens?: boolean;
407
716
  };
408
717
 
409
718
  export type BottomTabHeaderProps = {
410
- /**
411
- * Layout of the screen.
412
- */
413
- layout: Layout;
414
719
  /**
415
720
  * Options for the current screen.
416
721
  */
@@ -429,7 +734,6 @@ export type BottomTabBarProps = {
429
734
  state: TabNavigationState<ParamListBase>;
430
735
  descriptors: BottomTabDescriptorMap;
431
736
  navigation: NavigationHelpers<ParamListBase, BottomTabNavigationEventMap>;
432
- insets: EdgeInsets;
433
737
  };
434
738
 
435
739
  export type BottomTabBarButtonProps = Omit<
@@ -446,7 +750,6 @@ export type BottomTabBarButtonProps = Omit<
446
750
 
447
751
  export type BottomTabNavigatorProps = DefaultNavigatorOptions<
448
752
  ParamListBase,
449
- string | undefined,
450
753
  TabNavigationState<ParamListBase>,
451
754
  BottomTabNavigationOptions,
452
755
  BottomTabNavigationEventMap,