@react-navigation/bottom-tabs 8.0.0-alpha.55 → 8.0.0-alpha.57

package/src/types.tsx

@@ -194,7 +194,7 @@ type BottomTabCustomOptions = {
    *
    * Only supported with `custom` implementation.
    */
-  tabBarIconStyle?: StyleProp<TextStyle>;
+  tabBarIconStyle?: StyleProp<ViewStyle>;
 
   /**
    * Whether the tab bar gets hidden when the keyboard is shown.
@@ -274,19 +274,106 @@ type BottomTabCustomOptions = {
     | undefined;
 };
 
+type TabBarLabelOffset = {
+  horizontal?: number | undefined;
+  vertical?: number | undefined;
+};
+
 type BottomTabNativeOptions = {
   /**
    * Uses iOS built-in tab bar items with standard iOS styling and localized titles.
-   * If set to `search`, it's positioned next to the tab bar on iOS 26 and above.
    *
-   * The `tabBarIcon` and `tabBarLabel` options will override the icon and label from the system item.
+   * The `tabBarIcon` and `tabBarLabel` options override the icon and label from the system item.
    * If you want to keep the system behavior on iOS, but need to provide icon and label for other platforms,
    * Use `Platform.OS`  or `Platform.select`  to conditionally set `undefined` for `tabBarIcon` and `tabBarLabel` on iOS.
    *
+   * If set to `search`, it may receive the prominent visual treatment on iOS 26.
+   * See `tabBarRole` for more details on iOS 27 and above.
+   *
    * @platform ios
    */
   tabBarSystemItem?: TabsScreenSystemItem | undefined;
 
+  /**
+   * The role of the tab within the system tab bar.
+   *
+   * Supported values:
+   * - `prominent` - the tab gets the prominent visual treatment when supported
+   * - `search` - the tab is used as the system search tab
+   *
+   * If set to `prominent`, the tab may receive special styling to make it stand out,
+   * e.g., being positioned as a separate button next to the tab bar on iOS 27 and above.
+   * Only one tab can have the `prominent` role at a time.
+   * Supported on iOS 27 and above.
+   *
+   * If set to `search`, the tab gets the prominent visual treatment on iOS 26.
+   * On iOS 27 and above, it gets the prominent styling only if `tabBarSearchAutoFocus` is enabled,
+   * and no other tab has the `prominent` role.
+   * The tab uses system search icon and label by default.
+   * They can be overridden by `tabBarSystemItem`, `tabBarIcon`, and `tabBarLabel` options.
+   * Adding or removing the `search` role after the tab is rendered is not supported.
+   * Supported on iOS 26.1 and above.
+   *
+   * Only supported with `native` implementation.
+   *
+   * @platform ios
+   */
+  tabBarRole?: 'prominent' | 'search' | undefined;
+
+  /**
+   * Whether the search field is automatically focused when the tab is selected.
+   * Cancelling the search selects the previously selected tab.
+   *
+   * Only applies to tabs with `tabBarRole: 'search'`,
+   * and requires `headerSearchBarOptions` to be set in a native stack nested in the tab.
+   *
+   * Defaults to `false`.
+   *
+   * Only supported with `native` implementation.
+   *
+   * Supported on iOS 26.1 and above.
+   *
+   * @platform ios
+   */
+  tabBarSearchAutoFocus?: boolean | undefined;
+
+  /**
+   * Whether the sidebar or the tab bar is preferred when only one of them can be displayed.
+   *
+   * Supported values:
+   * - `auto` - uses the system default (tab bar)
+   * - `sidebar` - the sidebar is displayed when it's available
+   * - `tabBar` - the tab bar is displayed
+   *
+   * Requires `tabBarControllerMode` to be set to `tabSidebar`.
+   *
+   * The sidebar is only available when the horizontal size class is regular,
+   * e.g. on iPad, or on larger iPhones in landscape.
+   *
+   * Defaults to `auto`.
+   *
+   * Only supported with `native` implementation.
+   *
+   * Supported on iOS 27 and above.
+   * Not supported on tvOS.
+   *
+   * @platform ios
+   */
+  tabBarSidebarPreferredPlacement?: 'auto' | 'sidebar' | 'tabBar' | undefined;
+
+  /**
+   * Whether showing and hiding the tab bar is animated.
+   *
+   * Defaults to `true`.
+   *
+   * Only supported with `native` implementation.
+   *
+   * Supported on iOS 18 and above.
+   *
+   * @platform ios
+   */
+  tabBarVisibilityAnimationEnabled?: boolean | undefined;
+
   /**
    * Blur effect applied to the tab bar when tab screen is selected.
    *
@@ -337,6 +424,28 @@ type BottomTabNativeOptions = {
     | 'onScrollUp'
     | undefined;
 
+  /**
+   * Offset applied to the tab label relative to its default position.
+   * Positive `vertical` moves the label down, positive `horizontal` moves it right.
+   *
+   * The offset is specified separately for each tab bar item layout:
+   *
+   * - `stacked` - icon above the label, e.g. on iPhone in portrait
+   * - `inline` - icon beside the label in regular width, e.g. on iPad
+   * - `compactInline` - icon beside the label in compact width, e.g. on iPhone in landscape
+   *
+   * Only supported with `native` implementation.
+   *
+   * @platform ios
+   */
+  tabBarLabelPositionAdjustment?:
+    | {
+        stacked?: TabBarLabelOffset | undefined;
+        inline?: TabBarLabelOffset | undefined;
+        compactInline?: TabBarLabelOffset | undefined;
+      }
+    | undefined;
+
   /**
    * Background color of the active indicator.
    *
@@ -355,6 +464,24 @@ type BottomTabNativeOptions = {
    */
   tabBarActiveIndicatorEnabled?: boolean | undefined;
 
+  /**
+   * Width of the tab's active indicator.
+   *
+   * Only supported with `native` implementation.
+   *
+   * @platform android
+   */
+  tabBarActiveIndicatorWidth?: number | undefined;
+
+  /**
+   * Height of the tab's active indicator.
+   *
+   * Only supported with `native` implementation.
+   *
+   * @platform android
+   */
+  tabBarActiveIndicatorHeight?: number | undefined;
+
   /**
    * Function which returns a React element to display as an accessory view.
    *
@@ -431,6 +558,17 @@ export type BottomTabNavigationOptions = {
    */
   tabBarLabelVisibilityMode?: TabBarItemLabelVisibilityMode | undefined;
 
+  /**
+   * Size of the tab's icon.
+   *
+   * With `native` implementation, the largest size is used for the icon area in all tabs.
+   * Icons smaller than the largest size are centered in this area.
+   *
+   * Supported on all platforms with `custom` implementation.
+   * Only supported on Android with `native` implementation.
+   */
+  tabBarIconSize?: number | undefined;
+
   /**
    * Style object for the tab label.
    */
@@ -450,8 +588,6 @@ 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?:

package/src/views/BottomTabBar.tsx

@@ -15,6 +15,7 @@ import {
 import * as React from 'react';
 import {
   Animated,
+  type ColorValue,
   type LayoutChangeEvent,
   Platform,
   type StyleProp,
@@ -26,8 +27,14 @@ import {
   type EdgeInsets,
   useSafeAreaInsets,
 } from 'react-native-safe-area-context';
-
-import type { BottomTabBarProps, BottomTabDescriptorMap } from '../types';
+import type { TabBarItemLabelVisibilityMode } from 'react-native-screens';
+
+import type {
+  BottomTabBarProps,
+  BottomTabDescriptor,
+  BottomTabDescriptorMap,
+  BottomTabNavigationHelpers,
+} from '../types';
 import { BottomTabBarHeightCallbackContext } from '../utils/BottomTabBarHeightCallbackContext';
 import { useIsKeyboardShown } from '../utils/useIsKeyboardShown';
 import { useTabBarPosition } from '../utils/useTabBarPosition';
@@ -437,47 +444,6 @@ export function BottomTabBar({ state, navigation, descriptors, style }: Props) {
 
           const { options } = descriptor;
 
-          const onPress = () => {
-            const isRepeatedPress =
-              focused && options.tabBarSelectionEnabled !== false;
-
-            const event = navigation.emit({
-              type: 'tabPress',
-              target: route.key,
-              canPreventDefault: true,
-              data: {
-                behavior: {
-                  scrollToTop:
-                    isRepeatedPress &&
-                    options.tabBarRepeatedPressBehavior?.scrollToTop !== false,
-                  popToTop:
-                    isRepeatedPress &&
-                    options.tabBarRepeatedPressBehavior?.popToTop !== false,
-                },
-              },
-            });
-
-            if (
-              !focused &&
-              !event.defaultPrevented &&
-              options.tabBarSelectionEnabled !== false
-            ) {
-              React.startTransition(() => {
-                navigation.dispatch({
-                  ...CommonActions.navigate(route.name, route.params),
-                  target: state.key,
-                });
-              });
-            }
-          };
-
-          const onLongPress = () => {
-            navigation.emit({
-              type: 'tabLongPress',
-              target: route.key,
-            });
-          };
-
           const label =
             typeof options.tabBarLabel === 'function'
               ? options.tabBarLabel
@@ -496,52 +462,27 @@ export function BottomTabBar({ state, navigation, descriptors, style }: Props) {
                 : undefined;
 
           return (
-            <NavigationProvider
+            <BottomTabBarItem
               key={route.key}
-              navigation={descriptor.navigation}
               route={route}
-            >
-              <BottomTabItem
-                href={buildHref(route.name, route.params)}
-                route={route}
-                descriptor={descriptor}
-                focused={focused}
-                horizontal={hasHorizontalLabels}
-                compact={compact}
-                sidebar={sidebar}
-                variant={tabBarVariant}
-                onPress={onPress}
-                onLongPress={onLongPress}
-                accessibilityLabel={accessibilityLabel}
-                testID={options.tabBarButtonTestID}
-                allowFontScaling={options.tabBarAllowFontScaling}
-                activeTintColor={tabBarActiveTintColor}
-                inactiveTintColor={tabBarInactiveTintColor}
-                activeBackgroundColor={tabBarActiveBackgroundColor}
-                inactiveBackgroundColor={tabBarInactiveBackgroundColor}
-                rippleColor={options.tabBarRippleColor}
-                button={options.tabBarButton}
-                icon={options.tabBarIcon}
-                badge={options.tabBarBadge}
-                badgeStyle={options.tabBarBadgeStyle}
-                label={label}
-                labelVisibilityMode={tabBarLabelVisibilityMode}
-                labelStyle={options.tabBarLabelStyle}
-                iconStyle={options.tabBarIconStyle}
-                style={[
-                  sidebar
-                    ? {
-                        marginVertical: hasHorizontalLabels
-                          ? tabBarVariant === 'material'
-                            ? 0
-                            : 1
-                          : spacing / 2,
-                      }
-                    : styles.bottomItem,
-                  options.tabBarItemStyle,
-                ]}
-              />
-            </NavigationProvider>
+              descriptor={descriptor}
+              navigation={navigation}
+              navigatorKey={state.key}
+              href={buildHref(route.name, route.params)}
+              focused={focused}
+              label={label}
+              accessibilityLabel={accessibilityLabel}
+              hasHorizontalLabels={hasHorizontalLabels}
+              compact={compact}
+              sidebar={sidebar}
+              tabBarVariant={tabBarVariant}
+              spacing={spacing}
+              tabBarActiveTintColor={tabBarActiveTintColor}
+              tabBarInactiveTintColor={tabBarInactiveTintColor}
+              tabBarActiveBackgroundColor={tabBarActiveBackgroundColor}
+              tabBarInactiveBackgroundColor={tabBarInactiveBackgroundColor}
+              tabBarLabelVisibilityMode={tabBarLabelVisibilityMode}
+            />
           );
         })}
       </View>
@@ -549,6 +490,136 @@ export function BottomTabBar({ state, navigation, descriptors, style }: Props) {
   );
 }
 
+type BottomTabBarItemProps = {
+  route: TabNavigationState<ParamListBase>['routes'][number];
+  descriptor: BottomTabDescriptor;
+  navigation: BottomTabNavigationHelpers;
+  navigatorKey: string;
+  href: string | undefined;
+  focused: boolean;
+  label: React.ComponentProps<typeof BottomTabItem>['label'];
+  accessibilityLabel: string | undefined;
+  hasHorizontalLabels: boolean;
+  compact: boolean;
+  sidebar: boolean;
+  tabBarVariant: 'uikit' | 'material';
+  spacing: number;
+  tabBarActiveTintColor: ColorValue | undefined;
+  tabBarInactiveTintColor: ColorValue | undefined;
+  tabBarActiveBackgroundColor: ColorValue | undefined;
+  tabBarInactiveBackgroundColor: ColorValue | undefined;
+  tabBarLabelVisibilityMode: TabBarItemLabelVisibilityMode | undefined;
+};
+
+const BottomTabBarItem = React.memo(function BottomTabBarItem({
+  route,
+  descriptor,
+  navigation,
+  navigatorKey,
+  href,
+  focused,
+  label,
+  accessibilityLabel,
+  hasHorizontalLabels,
+  compact,
+  sidebar,
+  tabBarVariant,
+  spacing,
+  tabBarActiveTintColor,
+  tabBarInactiveTintColor,
+  tabBarActiveBackgroundColor,
+  tabBarInactiveBackgroundColor,
+  tabBarLabelVisibilityMode,
+}: BottomTabBarItemProps) {
+  const { options } = descriptor;
+
+  const onPress = () => {
+    const isRepeatedPress = focused && options.tabBarSelectionEnabled !== false;
+
+    const event = navigation.emit({
+      type: 'tabPress',
+      target: route.key,
+      canPreventDefault: true,
+      data: {
+        behavior: {
+          scrollToTop:
+            isRepeatedPress &&
+            options.tabBarRepeatedPressBehavior?.scrollToTop !== false,
+          popToTop:
+            isRepeatedPress &&
+            options.tabBarRepeatedPressBehavior?.popToTop !== false,
+        },
+      },
+    });
+
+    if (
+      !focused &&
+      !event.defaultPrevented &&
+      options.tabBarSelectionEnabled !== false
+    ) {
+      React.startTransition(() => {
+        navigation.dispatch({
+          ...CommonActions.navigate(route.name, route.params),
+          target: navigatorKey,
+        });
+      });
+    }
+  };
+
+  const onLongPress = () => {
+    navigation.emit({
+      type: 'tabLongPress',
+      target: route.key,
+    });
+  };
+
+  return (
+    <NavigationProvider navigation={descriptor.navigation} route={route}>
+      <BottomTabItem
+        href={href}
+        route={route}
+        descriptor={descriptor}
+        focused={focused}
+        horizontal={hasHorizontalLabels}
+        compact={compact}
+        sidebar={sidebar}
+        variant={tabBarVariant}
+        onPress={onPress}
+        onLongPress={onLongPress}
+        accessibilityLabel={accessibilityLabel}
+        testID={options.tabBarButtonTestID}
+        allowFontScaling={options.tabBarAllowFontScaling}
+        activeTintColor={tabBarActiveTintColor}
+        inactiveTintColor={tabBarInactiveTintColor}
+        activeBackgroundColor={tabBarActiveBackgroundColor}
+        inactiveBackgroundColor={tabBarInactiveBackgroundColor}
+        rippleColor={options.tabBarRippleColor}
+        button={options.tabBarButton}
+        icon={options.tabBarIcon}
+        badge={options.tabBarBadge}
+        badgeStyle={options.tabBarBadgeStyle}
+        label={label}
+        labelVisibilityMode={tabBarLabelVisibilityMode}
+        labelStyle={options.tabBarLabelStyle}
+        iconSize={options.tabBarIconSize}
+        iconStyle={options.tabBarIconStyle}
+        style={[
+          sidebar
+            ? {
+                marginVertical: hasHorizontalLabels
+                  ? tabBarVariant === 'material'
+                    ? 0
+                    : 1
+                  : spacing / 2,
+              }
+            : styles.bottomItem,
+          options.tabBarItemStyle,
+        ]}
+      />
+    </NavigationProvider>
+  );
+});
+
 const styles = StyleSheet.create({
   start: {
     top: 0,

package/src/views/BottomTabItem.tsx

@@ -135,6 +135,10 @@ type Props = {
    * Style object for the label element.
    */
   labelStyle?: StyleProp<TextStyle> | undefined;
+  /**
+   * Size of the icon.
+   */
+  iconSize?: number | undefined;
   /**
    * Style object for the icon element.
    */
@@ -181,6 +185,7 @@ export function BottomTabItem({
   // https://developer.apple.com/documentation/uikit/uiview/3183939-largecontenttitle
   allowFontScaling = SUPPORTS_LARGE_CONTENT_VIEWER ? false : undefined,
   labelStyle,
+  iconSize,
   iconStyle,
   style,
 }: Props) {
@@ -290,6 +295,7 @@ export function BottomTabItem({
         route={route}
         variant={variant}
         size={compact ? 'compact' : 'regular'}
+        iconSize={iconSize}
         badge={badge}
         badgeStyle={badgeStyle}
         activeOpacity={activeOpacity}

package/src/views/BottomTabViewCustom.tsx

@@ -4,6 +4,7 @@ import {
   SafeAreaProviderCompat,
 } from '@react-navigation/elements/internal';
 import {
+  type NavigationRoute,
   type ParamListBase,
   StackActions,
   type TabNavigationState,
@@ -23,6 +24,7 @@ import {
 } from '../TransitionConfigs/TransitionPresets';
 import type {
   BottomTabBarProps,
+  BottomTabDescriptor,
   BottomTabDescriptorMap,
   BottomTabNavigationConfig,
   BottomTabNavigationHelpers,
@@ -275,21 +277,12 @@ export function BottomTabViewCustom({
             );
           }
 
-          const { navigation, options, render } = descriptor;
-
-          const {
-            lazy = true,
-            inactiveBehavior = 'pause',
-            animation = 'none',
-            sceneStyleInterpolator = NAMED_TRANSITIONS_PRESETS[animation]
-              .sceneStyleInterpolator,
-            sceneStyle: customSceneStyle,
-          } = options;
+          const { lazy = true, inactiveBehavior = 'pause' } =
+            descriptor.options;
 
           const isFocused = state.index === index;
           const isPreloaded = state.preloadedRouteKeys.includes(route.key);
 
-          const animationEnabled = hasAnimation(descriptor.options);
           const tabAnimation = tabAnims[route.key];
 
           if (tabAnimation == null) {
@@ -298,29 +291,6 @@ export function BottomTabViewCustom({
             );
           }
 
-          const content = (
-            <AnimatedScreenContent
-              key={route.key}
-              progress={tabAnimation}
-              animationEnabled={animationEnabled}
-              sceneStyleInterpolator={sceneStyleInterpolator}
-              style={[StyleSheet.absoluteFill, customSceneStyle]}
-            >
-              <ScreenContent
-                isFocused={isFocused}
-                route={route}
-                navigation={navigation}
-                options={options}
-              >
-                <BottomTabBarHeightContext.Provider
-                  value={tabBarPosition === 'bottom' ? tabBarHeight : 0}
-                >
-                  {render()}
-                </BottomTabBarHeightContext.Provider>
-              </ScreenContent>
-            </AnimatedScreenContent>
-          );
-
           const isAnimatingRoute =
             lastUpdate.animating &&
             (lastUpdate.previous === route.key ||
@@ -335,22 +305,18 @@ export function BottomTabViewCustom({
             (lazy === false && !loaded.includes(route.key));
 
           return (
-            <Deferred
+            <TabScene
               key={route.key}
+              route={route}
+              descriptor={descriptor}
               lazy={lazy}
               visible={isFocused || isPreloaded || loaded.includes(route.key)}
-            >
-              <ActivityView
-                mode={isFocused ? 'normal' : isActive ? 'inert' : 'paused'}
-                visible={isFocused || isAnimatingRoute}
-                style={{
-                  ...StyleSheet.absoluteFill,
-                  zIndex: isFocused ? 0 : -1,
-                }}
-              >
-                {content}
-              </ActivityView>
-            </Deferred>
+              isFocused={isFocused}
+              isActive={isActive}
+              isAnimatingRoute={isAnimatingRoute}
+              tabAnimation={tabAnimation}
+              tabBarHeight={tabBarPosition === 'bottom' ? tabBarHeight : 0}
+            />
           );
         })}
       </Container>
@@ -361,6 +327,77 @@ export function BottomTabViewCustom({
   );
 }
 
+type TabSceneProps = {
+  route: NavigationRoute<ParamListBase, string>;
+  descriptor: BottomTabDescriptor;
+  lazy: boolean;
+  visible: boolean;
+  isFocused: boolean;
+  isActive: boolean;
+  isAnimatingRoute: boolean;
+  tabAnimation: Animated.Value;
+  tabBarHeight: number;
+};
+
+const TabScene = React.memo(function TabScene({
+  route,
+  descriptor,
+  lazy,
+  visible,
+  isFocused,
+  isActive,
+  isAnimatingRoute,
+  tabAnimation,
+  tabBarHeight,
+}: TabSceneProps) {
+  const { navigation, options, render } = descriptor;
+
+  const {
+    animation = 'none',
+    sceneStyleInterpolator = NAMED_TRANSITIONS_PRESETS[animation]
+      .sceneStyleInterpolator,
+    sceneStyle: customSceneStyle,
+  } = options;
+
+  const animationEnabled = hasAnimation(descriptor.options);
+
+  const content = (
+    <AnimatedScreenContent
+      key={route.key}
+      progress={tabAnimation}
+      animationEnabled={animationEnabled}
+      sceneStyleInterpolator={sceneStyleInterpolator}
+      style={[StyleSheet.absoluteFill, customSceneStyle]}
+    >
+      <ScreenContent
+        isFocused={isFocused}
+        route={route}
+        navigation={navigation}
+        options={options}
+      >
+        <BottomTabBarHeightContext.Provider value={tabBarHeight}>
+          {render()}
+        </BottomTabBarHeightContext.Provider>
+      </ScreenContent>
+    </AnimatedScreenContent>
+  );
+
+  return (
+    <Deferred lazy={lazy} visible={visible}>
+      <ActivityView
+        mode={isFocused ? 'normal' : isActive ? 'inert' : 'paused'}
+        visible={isFocused || isAnimatingRoute}
+        style={{
+          ...StyleSheet.absoluteFill,
+          zIndex: isFocused ? 0 : -1,
+        }}
+      >
+        {content}
+      </ActivityView>
+    </Deferred>
+  );
+});
+
 function AnimatedScreenContent({
   progress,
   animationEnabled,