@react-navigation/bottom-tabs 8.0.0-alpha.3 → 8.0.0-alpha.31

package/src/types.tsx

@@ -1,11 +1,12 @@
 import type {
   HeaderOptions,
+  Icon,
   PlatformPressable,
 } from '@react-navigation/elements';
+import type { Screen } from '@react-navigation/elements/internal';
 import type {
   DefaultNavigatorOptions,
   Descriptor,
-  MaterialSymbolProps,
   NavigationHelpers,
   NavigationProp,
   ParamListBase,
@@ -20,7 +21,6 @@ import type {
   Animated,
   ColorValue,
   GestureResponderEvent,
-  ImageSourcePropType,
   StyleProp,
   TextStyle,
   ViewStyle,
@@ -28,9 +28,8 @@ import type {
 import type {
   TabBarItemLabelVisibilityMode,
   TabsScreenBlurEffect,
-  TabsSystemItem,
+  TabsScreenSystemItem,
 } from 'react-native-screens';
-import type { SFSymbol } from 'sf-symbols-typescript';
 
 export type Variant = 'uikit' | 'material';
 
@@ -39,6 +38,7 @@ export type BottomTabNavigationEventMap = {
    * Event which fires on tapping on the tab in the tab bar.
    *
    * Preventing default is only supported with `custom` implementation.
+   * Use `tabBarSelectionEnabled: false` option with `native` implementation.
    */
   tabPress: { data: undefined; canPreventDefault: true };
   /**
@@ -114,75 +114,6 @@ export type TabBarVisibilityAnimationConfig =
 
 export type TabAnimationName = 'none' | 'fade' | 'shift';
 
-type IconImage = {
-  /**
-   * - `image` - Use a local image as the icon.
-   */
-  type: 'image';
-  /**
-   * Image source to use as the icon.
-   * e.g., `require('./path/to/image.png')`
-   */
-  source: ImageSourcePropType;
-  /**
-   * Whether to apply tint color to the icon.
-   * Defaults to `true`.
-   *
-   * @platform ios
-   */
-  tinted?: boolean;
-};
-
-type IconSfSymbol = {
-  /**
-   * - `sfSymbol` - Use an SF Symbol as the icon on iOS.
-   */
-  type: 'sfSymbol';
-  /**
-   * Name of the SF Symbol to use as the icon.
-   *
-   * @platform ios
-   */
-  name: SFSymbol;
-};
-
-type IconMaterialSymbol = {
-  /**
-   * - `materialSymbol` - Use a Material Symbol as the icon on Android.
-   */
-  type: 'materialSymbol';
-  /**
-   * Name of the Material Symbol to use as the icon.
-   *
-   * @platform android
-   */
-  name: MaterialSymbolProps['name'];
-};
-
-type IconResource = {
-  /**
-   * - `resource` - Use a resource from drawables on Android and xcassets asset catalog on iOS as the icon.
-   */
-  type: 'resource';
-  /**
-   * Name of the drawable resource or xcasset to use as the icon.
-   */
-  name: string;
-  /**
-   * Whether to apply tint color to the icon.
-   * Only supported with custom implementation.
-   *
-   * Defaults to `true`.
-   */
-  tinted?: boolean;
-};
-
-type IconIOS = IconSfSymbol | IconImage;
-
-type IconAndroid = IconMaterialSymbol | IconResource | IconImage;
-
-export type BottomTabIcon = IconIOS | IconAndroid;
-
 type BottomTabCustomOptions = {
   /**
    * How the screen should animate when switching tabs.
@@ -220,7 +151,7 @@ type BottomTabCustomOptions = {
    *
    * Only supported with `custom` implementation.
    */
-  tabBarLabelPosition?: LabelPosition;
+  tabBarLabelPosition?: LabelPosition | undefined;
 
   /**
    * Whether label font should scale to respect Text Size accessibility settings.
@@ -319,8 +250,6 @@ type BottomTabCustomOptions = {
   tabBarButton?: (props: BottomTabBarButtonProps) => React.ReactNode;
 };
 
-type ScrollEdgeEffect = 'auto' | 'hard' | 'soft' | 'hidden';
-
 type BottomTabNativeOptions = {
   /**
    * Uses iOS built-in tab bar items with standard iOS styling and localized titles.
@@ -332,7 +261,7 @@ type BottomTabNativeOptions = {
    *
    * @platform ios
    */
-  tabBarSystemItem?: TabsSystemItem;
+  tabBarSystemItem?: TabsScreenSystemItem;
 
   /**
    * Blur effect applied to the tab bar when tab screen is selected.
@@ -418,36 +347,25 @@ type BottomTabNativeOptions = {
   }) => React.ReactNode;
 
   /**
-   * Configures the scroll edge effect for the _content ScrollView_ (the ScrollView that is present in first descendants chain of the Screen).
-   * Depending on values set, it will blur the scrolling content below certain UI elements (header items, search bar)
-   * for the specified edge of the ScrollView.
-   *
-   * When set in nested containers, i.e. Native Stack inside Native Bottom Tabs, or the other way around,
-   * the ScrollView will use only the innermost one's config.
+   * Specifies whether `contentInsetAdjustmentBehavior` of the `ScrollView`
+   * in the screen is automatically adjusted.
    *
-   * **Note:** Using both `headerBlurEffect` and `scrollEdgeEffects` (>= iOS 26) simultaneously may cause overlapping effects.
+   * `react-native`'s `ScrollView`s has `contentInsetAdjustmentBehavior` set to `never` by default.
+   * To provide a better UX, it is overridden to `automatic` - so it respects the tab bar.
+   * Otherwise, content can get hidden behind the tab bar as it's translucent on iOS 26+.
    *
-   * Edge effects can be configured for each edge separately. The following values are currently supported:
+   * Note that this only affects the `ScrollView` in first descendant chain of the screen,
+   * i.e., first view of each nested view is checked until a `ScrollView` is found.
    *
-   * - `auto` - the automatic scroll edge effect style,
-   * - `hard` - a scroll edge effect with a hard cutoff and dividing line,
-   * - `soft` - a soft-edged scroll edge effect,
-   * - `hidden` - no scroll edge effect.
-   *
-   * Defaults to `automatic` for each edge.
-   *
-   * Available starting from iOS 26.
+   * To disable this behavior for specific screens, set this option to `false`.
    *
    * Only supported with `native` implementation.
    *
+   * Defaults to `true`.
+   *
    * @platform ios
    */
-  scrollEdgeEffects?: {
-    bottom?: ScrollEdgeEffect;
-    left?: ScrollEdgeEffect;
-    right?: ScrollEdgeEffect;
-    top?: ScrollEdgeEffect;
-  };
+  overrideScrollViewContentInsetAdjustmentBehavior?: boolean;
 };
 
 export type BottomTabNavigationOptions = {
@@ -489,7 +407,7 @@ export type BottomTabNavigationOptions = {
    */
   tabBarLabelStyle?: Pick<
     TextStyle,
-    'fontFamily' | 'fontSize' | 'fontWeight' | 'fontStyle'
+    'fontFamily' | 'fontSize' | 'fontWeight' | 'fontStyle' | 'color'
   >;
 
   /**
@@ -501,26 +419,30 @@ export type BottomTabNavigationOptions = {
    * - on all platforms with `custom` implementation
    * - on iOS with `native` implementation
    *
+   * With `native` implementation, `tinted` for `image` can only be disabled on iOS.
+   *
    * A React element is only supported with `custom` implementation.
    */
   tabBarIcon?:
-    | BottomTabIcon
+    | Icon
     | ((props: {
         focused: boolean;
         color: ColorValue;
         size: number;
-      }) => BottomTabIcon | React.ReactNode);
+      }) => Icon | React.ReactNode);
 
   /**
    * Text to show in a badge on the tab icon.
    */
-  tabBarBadge?: number | string;
+  tabBarBadge?: number | string | undefined;
 
   /**
    * Custom style for the tab bar badge.
    * You can specify a background color or text color here.
    *
-   * @platform android
+   * With `native` implementation, limited customization is supported:
+   * - on iOS, you can only set the background color.
+   * - on Android, you can set both background and text colors.
    */
   tabBarBadgeStyle?: {
     backgroundColor?: ColorValue;
@@ -530,7 +452,7 @@ export type BottomTabNavigationOptions = {
   /**
    * Color for the icon and label in the active tab.
    */
-  tabBarActiveTintColor?: ColorValue;
+  tabBarActiveTintColor?: ColorValue | undefined;
 
   /**
    * Color for the icon and label in the inactive tabs.
@@ -590,8 +512,22 @@ export type BottomTabNavigationOptions = {
      * Only supported on iOS 18 and below.
      */
     shadowColor?: ColorValue;
+    /**
+     * Whether the tab bar is visible.
+     * Setting this to `'none'` hides the tab bar.
+     */
+    display?: 'flex' | 'none';
   };
 
+  /**
+   * Whether this tab can be selected.
+   * When `false`, tapping on the tab in tab bar won't select the tab.
+   * Custom behavior can be implemented by listening to `tabPress` event.
+   *
+   * Defaults to `true`.
+   */
+  tabBarSelectionEnabled?: boolean;
+
   /**
    * Whether this screens should render the first time it's accessed. Defaults to `true`.
    * Set it to `false` if you want to render the screen on initial render.
@@ -607,7 +543,7 @@ export type BottomTabNavigationOptions = {
   /**
    * Style object for the component wrapping the screen content.
    */
-  sceneStyle?: StyleProp<ViewStyle>;
+  sceneStyle?: React.ComponentProps<typeof Screen>['style'];
 
   /**
    * Function that returns a React Element to display as a header.
@@ -620,6 +556,19 @@ export type BottomTabNavigationOptions = {
    * Defaults to `false` unless a header is provided.
    */
   headerShown?: boolean;
+
+  /**
+   * What should happen when screens become inactive.
+   * - `pause`: Effects are cleaned up.
+   * - `none`: Screen renders normally
+   *
+   * Defaults to `pause`.
+   *
+   * If you set `lazy: false` or preload a screen,
+   * It won't be paused until after the first time it becomes focused.
+   * This makes sure that effects are run to initialize the screen.
+   */
+  inactiveBehavior?: 'pause' | 'none';
 } & HeaderOptions &
   BottomTabNativeOptions &
   BottomTabCustomOptions;
@@ -710,15 +659,6 @@ export type BottomTabNavigationConfig = {
    * Function that returns a React element to display as the tab bar.
    */
   tabBar?: (props: BottomTabBarProps) => React.ReactNode;
-
-  /**
-   * Whether inactive screens should be detached from the view hierarchy to save memory.
-   *
-   * Defaults to `true`.
-   *
-   * Only supported with `custom` implementation.
-   */
-  detachInactiveScreens?: boolean;
 };
 
 export type BottomTabHeaderProps = {
@@ -746,7 +686,7 @@ export type BottomTabBarButtonProps = Omit<
   React.ComponentProps<typeof PlatformPressable>,
   'style'
 > & {
-  href?: string;
+  href?: string | undefined;
   children: React.ReactNode;
   style?: StyleProp<ViewStyle>;
   onPress?: (

package/src/utils/useBottomTabAnimation.tsx

@@ -3,7 +3,7 @@ import * as React from 'react';
 import { BottomTabAnimationContext } from './BottomTabAnimationContext';
 
 export function useBottomTabAnimation() {
-  const animation = React.useContext(BottomTabAnimationContext);
+  const animation = React.use(BottomTabAnimationContext);
 
   if (animation === undefined) {
     throw new Error(

package/src/utils/useBottomTabBarHeight.tsx

@@ -3,7 +3,7 @@ import * as React from 'react';
 import { BottomTabBarHeightContext } from './BottomTabBarHeightContext';
 
 export function useBottomTabBarHeight() {
-  const height = React.useContext(BottomTabBarHeightContext);
+  const height = React.use(BottomTabBarHeightContext);
 
   if (height === undefined) {
     throw new Error(

package/src/views/BottomTabBar.tsx

@@ -207,7 +207,7 @@ export function BottomTabBar({ state, navigation, descriptors, style }: Props) {
   const insets = useSafeAreaInsets();
   const isKeyboardShown = useIsKeyboardShown();
 
-  const onHeightChange = React.useContext(BottomTabBarHeightCallbackContext);
+  const onHeightChange = React.use(BottomTabBarHeightCallbackContext);
 
   const shouldShowTabBar = !(tabBarHideOnKeyboard && isKeyboardShown);
 
@@ -228,18 +228,22 @@ export function BottomTabBar({ state, navigation, descriptors, style }: Props) {
   React.useEffect(() => {
     const visibilityAnimationConfig = visibilityAnimationConfigRef.current;
 
+    let animation;
+
     if (shouldShowTabBar) {
-      const animation =
+      const animate =
         visibilityAnimationConfig?.show?.animation === 'spring'
           ? Animated.spring
           : Animated.timing;
 
-      animation(visible, {
+      animation = animate(visible, {
         toValue: 1,
         useNativeDriver,
         duration: 250,
         ...visibilityAnimationConfig?.show?.config,
-      }).start(({ finished }) => {
+      });
+
+      animation.start(({ finished }) => {
         if (finished) {
           setIsTabBarHidden(false);
         }
@@ -248,20 +252,22 @@ export function BottomTabBar({ state, navigation, descriptors, style }: Props) {
       // eslint-disable-next-line @eslint-react/hooks-extra/no-direct-set-state-in-use-effect
       setIsTabBarHidden(true);
 
-      const animation =
+      const animate =
         visibilityAnimationConfig?.hide?.animation === 'spring'
           ? Animated.spring
           : Animated.timing;
 
-      animation(visible, {
+      animation = animate(visible, {
         toValue: 0,
         useNativeDriver,
         duration: 200,
         ...visibilityAnimationConfig?.hide?.config,
-      }).start();
+      });
+
+      animation.start();
     }
 
-    return () => visible.stopAnimation();
+    return () => animation.stop();
   }, [visible, shouldShowTabBar]);
 
   const [layout, setLayout] = React.useState({
@@ -343,7 +349,7 @@ export function BottomTabBar({ state, navigation, descriptors, style }: Props) {
               : { borderTopWidth: StyleSheet.hairlineWidth },
         {
           backgroundColor:
-            tabBarBackgroundElement != null ? 'transparent' : colors.card,
+            tabBarBackgroundElement != null ? 'transparent' : colors.background,
           borderColor: colors.border,
         },
         sidebar
@@ -409,7 +415,11 @@ export function BottomTabBar({ state, navigation, descriptors, style }: Props) {
               canPreventDefault: true,
             });
 
-            if (!focused && !event.defaultPrevented) {
+            if (
+              !focused &&
+              !event.defaultPrevented &&
+              options.tabBarSelectionEnabled !== false
+            ) {
               navigation.dispatch({
                 ...CommonActions.navigate(route),
                 target: state.key,
@@ -435,8 +445,10 @@ export function BottomTabBar({ state, navigation, descriptors, style }: Props) {
           const accessibilityLabel =
             options.tabBarAccessibilityLabel !== undefined
               ? options.tabBarAccessibilityLabel
-              : typeof label === 'string' && Platform.OS === 'ios'
-                ? `${label}, tab, ${index + 1} of ${routes.length}`
+              : typeof label === 'string'
+                ? Platform.OS === 'android'
+                  ? `${label}, ${index + 1} of ${routes.length}`
+                  : `${label}, ${focused ? 'selected' : 'unselected'}`
                 : undefined;
 
           return (

package/src/views/BottomTabItem.tsx

@@ -29,7 +29,7 @@ type Props = {
   /**
    * The `href` to use for the anchor tag on web
    */
-  href?: string;
+  href?: string | undefined;
   /**
    * Whether the tab is focused.
    */
@@ -56,23 +56,23 @@ type Props = {
   /**
    * Text to show in a badge on the tab icon.
    */
-  badge?: number | string;
+  badge?: number | string | undefined;
   /**
    * Custom style for the badge.
    */
-  badgeStyle?: StyleProp<TextStyle>;
+  badgeStyle?: StyleProp<TextStyle> | undefined;
   /**
    * The button for the tab. Uses a `Pressable` by default.
    */
-  button?: (props: BottomTabBarButtonProps) => React.ReactNode;
+  button?: ((props: BottomTabBarButtonProps) => React.ReactNode) | undefined;
   /**
    * The accessibility label for the tab.
    */
-  accessibilityLabel?: string;
+  accessibilityLabel?: string | undefined;
   /**
    * An unique ID for testing for the tab.
    */
-  testID?: string;
+  testID?: string | undefined;
   /**
    * Function to execute on press in React Native.
    * On the web, this will use onClick.
@@ -105,44 +105,44 @@ type Props = {
   /**
    * Color for the icon and label when the item is active.
    */
-  activeTintColor?: ColorValue;
+  activeTintColor?: ColorValue | undefined;
   /**
    * Color for the icon and label when the item is inactive.
    */
-  inactiveTintColor?: ColorValue;
+  inactiveTintColor?: ColorValue | undefined;
   /**
    * Background color for item when its active.
    */
-  activeBackgroundColor?: ColorValue;
+  activeBackgroundColor?: ColorValue | undefined;
   /**
    * Background color for item when its inactive.
    */
-  inactiveBackgroundColor?: ColorValue;
+  inactiveBackgroundColor?: ColorValue | undefined;
   /**
    * Color of tab bar item's ripple effect.
    */
-  rippleColor?: ColorValue;
+  rippleColor?: ColorValue | undefined;
   /**
    * Label visibility mode for the tab bar item.
    */
-  labelVisibilityMode?: TabBarItemLabelVisibilityMode;
+  labelVisibilityMode?: TabBarItemLabelVisibilityMode | undefined;
   /**
    * Whether to allow scaling the font for the label for accessibility purposes.
    * Defaults to `false` on iOS 13+ where it uses `largeContentTitle`.
    */
-  allowFontScaling?: boolean;
+  allowFontScaling?: boolean | undefined;
   /**
    * Style object for the label element.
    */
-  labelStyle?: StyleProp<TextStyle>;
+  labelStyle?: StyleProp<TextStyle> | undefined;
   /**
    * Style object for the icon element.
    */
-  iconStyle?: StyleProp<ViewStyle>;
+  iconStyle?: StyleProp<ViewStyle> | undefined;
   /**
    * Style object for the wrapper element.
    */
-  style?: StyleProp<ViewStyle>;
+  style?: StyleProp<ViewStyle> | undefined;
 };
 
 const renderButtonDefault = (props: BottomTabBarButtonProps) => (
@@ -189,9 +189,7 @@ export function BottomTabItem({
   const activeTintColor: ColorValue =
     customActiveTintColor ??
     (variant === 'uikit' && sidebar && horizontal
-      ? Color(colors.primary)?.isDark()
-        ? 'white'
-        : (Color(colors.primary)?.darken(0.71).string() ?? 'white')
+      ? Color.foreground(colors.primary)
       : colors.primary);
 
   const inactiveTintColor: ColorValue =