@react-navigation/bottom-tabs 8.0.0-alpha.2 → 8.0.0-alpha.21

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,
@@ -30,7 +30,6 @@ import type {
   TabsScreenBlurEffect,
   TabsSystemItem,
 } from 'react-native-screens';
-import type { SFSymbol } from 'sf-symbols-typescript';
 
 export type Variant = 'uikit' | 'material';
 
@@ -114,79 +113,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 IconIOSSfSymbol = {
-  /**
-   * - `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 IconAndroidDrawable = {
-  /**
-   * - `drawableResource` - Use a drawable resource as the icon on Android.
-   */
-  type: 'drawableResource';
-  /**
-   * Name of the drawable resource to use as the icon.
-   *
-   * @platform android
-   */
-  name: string;
-  /**
-   * Whether to apply tint color to the icon.
-   * Only supported with custom implementation.
-   *
-   * Defaults to `true`.
-   *
-   * @platform android
-   */
-  tinted?: boolean;
-};
-
-type IconIOS = IconIOSSfSymbol | IconImage;
-
-type IconAndroid = IconMaterialSymbol | IconAndroidDrawable | IconImage;
-
-export type BottomTabIcon = IconIOS | IconAndroid;
-
 type BottomTabCustomOptions = {
   /**
    * How the screen should animate when switching tabs.
@@ -224,7 +150,7 @@ type BottomTabCustomOptions = {
    *
    * Only supported with `custom` implementation.
    */
-  tabBarLabelPosition?: LabelPosition;
+  tabBarLabelPosition?: LabelPosition | undefined;
 
   /**
    * Whether label font should scale to respect Text Size accessibility settings.
@@ -235,21 +161,6 @@ type BottomTabCustomOptions = {
    */
   tabBarAllowFontScaling?: boolean;
 
-  /**
-   * Accessibility label for the tab button. This is read by the screen reader when the user taps the tab.
-   * It's recommended to set this if you don't have a label for the tab.
-   *
-   * Only supported with `custom` implementation.
-   */
-  tabBarAccessibilityLabel?: string;
-
-  /**
-   * ID to locate this tab button in tests.
-   *
-   * Only supported with `custom` implementation.
-   */
-  tabBarButtonTestID?: string;
-
   /**
    * Style object for the tab item container.
    *
@@ -467,6 +378,27 @@ type BottomTabNativeOptions = {
     right?: ScrollEdgeEffect;
     top?: ScrollEdgeEffect;
   };
+
+  /**
+   * Specifies whether `contentInsetAdjustmentBehavior` of the `ScrollView`
+   * in the screen is automatically adjusted.
+   *
+   * `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+.
+   *
+   * 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.
+   *
+   * To disable this behavior for specific screens, set this option to `false`.
+   *
+   * Only supported with `native` implementation.
+   *
+   * Defaults to `true`.
+   *
+   * @platform ios
+   */
+  overrideScrollViewContentInsetAdjustmentBehavior?: boolean;
 };
 
 export type BottomTabNavigationOptions = {
@@ -508,7 +440,7 @@ export type BottomTabNavigationOptions = {
    */
   tabBarLabelStyle?: Pick<
     TextStyle,
-    'fontFamily' | 'fontSize' | 'fontWeight' | 'fontStyle'
+    'fontFamily' | 'fontSize' | 'fontWeight' | 'fontStyle' | 'color'
   >;
 
   /**
@@ -520,26 +452,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;
@@ -549,7 +485,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.
@@ -582,6 +518,17 @@ export type BottomTabNavigationOptions = {
    */
   tabBarControllerMode?: 'auto' | 'tabBar' | 'tabSidebar';
 
+  /**
+   * Accessibility label for the tab button. This is read by the screen reader when the user taps the tab.
+   * It's recommended to set this if you don't have a label for the tab.
+   */
+  tabBarAccessibilityLabel?: string;
+
+  /**
+   * ID to locate this tab button in tests.
+   */
+  tabBarButtonTestID?: string;
+
   /**
    * Style object for the tab bar container.
    */
@@ -598,6 +545,11 @@ 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';
   };
 
   /**
@@ -615,7 +567,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.
@@ -628,6 +580,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;
@@ -718,15 +683,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 = {
@@ -754,7 +710,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
@@ -435,8 +441,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 =