@react-navigation/bottom-tabs 8.0.0-alpha.4 → 8.0.0-alpha.40

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,67 +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.
-   */
-  name: SFSymbol;
-};
-
-type IconMaterialSymbol = {
-  /**
-   * - `materialSymbol` - Use a Material Symbol as the icon on Android.
-   */
-  type: 'materialSymbol';
-} & Pick<MaterialSymbolProps, 'name' | 'variant' | 'weight'>;
-
-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.
@@ -212,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.
@@ -311,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.
@@ -324,7 +261,7 @@ type BottomTabNativeOptions = {
    *
    * @platform ios
    */
-  tabBarSystemItem?: TabsSystemItem;
+  tabBarSystemItem?: TabsScreenSystemItem;
 
   /**
    * Blur effect applied to the tab bar when tab screen is selected.
@@ -410,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.
-   *
-   * **Note:** Using both `headerBlurEffect` and `scrollEdgeEffects` (>= iOS 26) simultaneously may cause overlapping effects.
+   * Specifies whether `contentInsetAdjustmentBehavior` of the `ScrollView`
+   * in the screen is automatically adjusted.
    *
-   * Edge effects can be configured for each edge separately. The following values are currently supported:
+   * `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+.
    *
-   * - `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.
+   * 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.
    *
-   * 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 = {
@@ -481,7 +407,7 @@ export type BottomTabNavigationOptions = {
    */
   tabBarLabelStyle?: Pick<
     TextStyle,
-    'fontFamily' | 'fontSize' | 'fontWeight' | 'fontStyle'
+    'fontFamily' | 'fontSize' | 'fontWeight' | 'fontStyle' | 'color'
   >;
 
   /**
@@ -493,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;
@@ -522,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.
@@ -582,11 +512,31 @@ 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 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.
+   * 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 screen should render only when first accessed.
+   *
+   * Defaults to:
+   * - `true` with custom implementation.
+   * - `false` with native implementation.
+   *
+   * Enabling in native implementation may result in flicker
+   * as React renders after native transition is already finished.
    */
   lazy?: boolean;
 
@@ -599,7 +549,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.
@@ -612,6 +562,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;
@@ -702,15 +665,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 = {
@@ -738,7 +692,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/useAnimatedHashMap.tsx

@@ -1,4 +1,4 @@
-import type { NavigationState } from '@react-navigation/routers';
+import type { NavigationState } from '@react-navigation/native';
 import * as React from 'react';
 import { Animated } from 'react-native';
 

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

@@ -12,7 +12,7 @@ import {
   useLocale,
   useTheme,
 } from '@react-navigation/native';
-import React from 'react';
+import * as React from 'react';
 import {
   Animated,
   type LayoutChangeEvent,
@@ -57,8 +57,11 @@ const shouldUseHorizontalLabels = ({
 }: Options & {
   dimensions: { height: number; width: number };
 }) => {
-  const { tabBarLabelPosition } =
-    descriptors[state.routes[state.index].key].options;
+  const focusedRoute = state.routes[state.index];
+  const tabBarLabelPosition =
+    focusedRoute == null
+      ? undefined
+      : descriptors[focusedRoute.key]?.options.tabBarLabelPosition;
 
   if (tabBarLabelPosition) {
     switch (tabBarLabelPosition) {
@@ -72,8 +75,9 @@ const shouldUseHorizontalLabels = ({
   if (dimensions.width >= 768) {
     // Screen size matches a tablet
     const maxTabWidth = state.routes.reduce((acc, route) => {
-      const { tabBarItemStyle } = descriptors[route.key].options;
-      const flattenedStyle = StyleSheet.flatten(tabBarItemStyle);
+      const flattenedStyle = StyleSheet.flatten(
+        descriptors[route.key]?.options.tabBarItemStyle
+      );
 
       if (flattenedStyle) {
         if (typeof flattenedStyle.width === 'number') {
@@ -97,8 +101,9 @@ const isCompact = ({
   descriptors,
   dimensions,
 }: Options & { dimensions: { height: number; width: number } }): boolean => {
+  const focusedRoute = state.routes[state.index];
   const { tabBarPosition, tabBarVariant } =
-    descriptors[state.routes[state.index].key].options;
+    focusedRoute == null ? {} : (descriptors[focusedRoute.key]?.options ?? {});
 
   if (
     tabBarPosition === 'left' ||
@@ -138,7 +143,11 @@ export const getTabBarHeight = ({
   dimensions: { height: number; width: number };
   style: Animated.WithAnimatedValue<StyleProp<ViewStyle>> | undefined;
 }) => {
-  const { tabBarPosition } = descriptors[state.routes[state.index].key].options;
+  const focusedRoute = state.routes[state.index];
+  const tabBarPosition =
+    focusedRoute == null
+      ? undefined
+      : descriptors[focusedRoute.key]?.options.tabBarPosition;
 
   const flattenedStyle = StyleSheet.flatten(style);
   const customHeight =
@@ -165,7 +174,19 @@ export function BottomTabBar({ state, navigation, descriptors, style }: Props) {
   const { buildHref } = useLinkBuilder();
 
   const focusedRoute = state.routes[state.index];
+
+  if (focusedRoute == null) {
+    throw new Error(`Couldn't find a route at index ${state.index}.`);
+  }
+
   const focusedDescriptor = descriptors[focusedRoute.key];
+
+  if (focusedDescriptor == null) {
+    throw new Error(
+      `Couldn't find a descriptor for route '${focusedRoute.key}'.`
+    );
+  }
+
   const focusedOptions = focusedDescriptor.options;
 
   const {
@@ -207,7 +228,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 +249,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 +273,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 +370,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
@@ -400,7 +427,15 @@ export function BottomTabBar({ state, navigation, descriptors, style }: Props) {
       >
         {routes.map((route, index) => {
           const focused = index === state.index;
-          const { options } = descriptors[route.key];
+          const descriptor = descriptors[route.key];
+
+          if (descriptor == null) {
+            throw new Error(
+              `Couldn't find a descriptor for route '${route.key}'.`
+            );
+          }
+
+          const { options } = descriptor;
 
           const onPress = () => {
             const event = navigation.emit({
@@ -409,10 +444,16 @@ export function BottomTabBar({ state, navigation, descriptors, style }: Props) {
               canPreventDefault: true,
             });
 
-            if (!focused && !event.defaultPrevented) {
-              navigation.dispatch({
-                ...CommonActions.navigate(route),
-                target: state.key,
+            if (
+              !focused &&
+              !event.defaultPrevented &&
+              options.tabBarSelectionEnabled !== false
+            ) {
+              React.startTransition(() => {
+                navigation.dispatch({
+                  ...CommonActions.navigate(route.name, route.params),
+                  target: state.key,
+                });
               });
             }
           };
@@ -435,20 +476,22 @@ 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 (
             <NavigationProvider
               key={route.key}
-              navigation={descriptors[route.key].navigation}
+              navigation={descriptor.navigation}
               route={route}
             >
               <BottomTabItem
                 href={buildHref(route.name, route.params)}
                 route={route}
-                descriptor={descriptors[route.key]}
+                descriptor={descriptor}
                 focused={focused}
                 horizontal={hasHorizontalLabels}
                 compact={compact}

package/src/views/BottomTabItem.tsx

@@ -1,7 +1,7 @@
 import { getLabel, Label, PlatformPressable } from '@react-navigation/elements';
 import { Color } from '@react-navigation/elements/internal';
 import { type Route, useTheme } from '@react-navigation/native';
-import React from 'react';
+import * as React from 'react';
 import {
   type ColorValue,
   type GestureResponderEvent,
@@ -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 =