@react-navigation/bottom-tabs 7.20.0 → 7.21.0

package/src/unstable/types.tsx

@@ -101,8 +101,6 @@ type IconImage = {
    * Disabling will keep the image's original colors.
    *
    * Defaults to `true`.
-   *
-   * @platform ios
    */
   tinted?: boolean;
 };
@@ -118,10 +116,25 @@ type IconIOSSfSymbol = {
    * @platform ios
    */
   name: SFSymbol;
+  /**
+   * How to color the symbol.
+   * - `monochrome`: Single color, using the tint color.
+   * - `multicolor`: Uses the symbol's built-in multicolor scheme.
+   *
+   * Defaults to a single color for system symbols.
+   *
+   * @platform ios
+   */
+  renderingMode?: 'monochrome' | 'multicolor';
 };
 
 export type NativeBottomTabIcon = IconIOSSfSymbol | IconImage;
 
+type TabBarLabelOffset = {
+  horizontal?: number;
+  vertical?: number;
+};
+
 export type NativeBottomTabNavigationOptions = NativeHeaderOptions & {
   /**
    * Title text for the screen.
@@ -130,16 +143,90 @@ export type NativeBottomTabNavigationOptions = NativeHeaderOptions & {
 
   /**
    * 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;
 
+  /**
+   * 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.
+   *
+   * @platform ios
+   */
+  tabBarRole?: 'prominent' | 'search';
+
+  /**
+   * 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`.
+   *
+   * Supported on iOS 26.1 and above.
+   *
+   * @platform ios
+   */
+  tabBarSearchAutoFocus?: boolean;
+
+  /**
+   * 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`.
+   *
+   * Supported on iOS 27 and above.
+   * Not supported on tvOS.
+   *
+   * @platform ios
+   */
+  tabBarSidebarPreferredPlacement?: 'auto' | 'sidebar' | 'tabBar';
+
+  /**
+   * Whether showing and hiding the tab bar is animated.
+   *
+   * Defaults to `true`.
+   *
+   * Supported on iOS 18 and above.
+   *
+   * @platform ios
+   */
+  tabBarVisibilityAnimationEnabled?: boolean;
+
   /**
    * Title string of the tab displayed in the tab bar
    *
@@ -186,6 +273,16 @@ export type NativeBottomTabNavigationOptions = NativeHeaderOptions & {
     | NativeBottomTabIcon
     | ((props: { focused: boolean }) => NativeBottomTabIcon);
 
+  /**
+   * Size of the tab's icon.
+   *
+   * The largest size is used for the icon area in all tabs.
+   * Icons smaller than the largest size are centered in this area.
+   *
+   * @platform android
+   */
+  tabBarIconSize?: number;
+
   /**
    * Text to show in a badge on the tab icon.
    */
@@ -228,6 +325,20 @@ export type NativeBottomTabNavigationOptions = NativeHeaderOptions & {
    */
   tabBarActiveIndicatorEnabled?: boolean;
 
+  /**
+   * Width of the tab's active indicator.
+   *
+   * @platform android
+   */
+  tabBarActiveIndicatorWidth?: number;
+
+  /**
+   * Height of the tab's active indicator.
+   *
+   * @platform android
+   */
+  tabBarActiveIndicatorHeight?: number;
+
   /**
    * Color of tab bar item's ripple effect.
    *
@@ -347,6 +458,24 @@ export type NativeBottomTabNavigationOptions = NativeHeaderOptions & {
    */
   tabBarMinimizeBehavior?: 'auto' | 'none' | 'onScrollDown' | 'onScrollUp';
 
+  /**
+   * 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
+   *
+   * @platform ios
+   */
+  tabBarLabelPositionAdjustment?: {
+    stacked?: TabBarLabelOffset;
+    inline?: TabBarLabelOffset;
+    compactInline?: TabBarLabelOffset;
+  };
+
   /**
    * Function which returns a React element to display as an accessory view.
    *

package/src/views/BottomTabBar.tsx

@@ -25,7 +25,13 @@ import {
 } from 'react-native';
 import { type EdgeInsets } from 'react-native-safe-area-context';
 
-import type { BottomTabBarProps, BottomTabDescriptorMap } from '../types';
+import type {
+  BottomTabBarProps,
+  BottomTabDescriptor,
+  BottomTabDescriptorMap,
+  LabelVisibilityMode,
+  Variant,
+} from '../types';
 import { BottomTabBarHeightCallbackContext } from '../utils/BottomTabBarHeightCallbackContext';
 import { useIsKeyboardShown } from '../utils/useIsKeyboardShown';
 import { BottomTabItem } from './BottomTabItem';
@@ -396,38 +402,6 @@ export function BottomTabBar({
           const focused = index === state.index;
           const { options } = descriptors[route.key];
 
-          const onPress = () => {
-            const event = navigation.emit({
-              type: 'tabPress',
-              target: route.key,
-              canPreventDefault: true,
-              data: {
-                behavior: {
-                  scrollToTop:
-                    focused &&
-                    options.tabBarRepeatedPressBehavior?.scrollToTop !== false,
-                  popToTop:
-                    focused &&
-                    options.tabBarRepeatedPressBehavior?.popToTop !== false,
-                },
-              },
-            });
-
-            if (!focused && !event.defaultPrevented) {
-              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
@@ -444,57 +418,28 @@ export function BottomTabBar({
                 : undefined;
 
           return (
-            <NavigationProvider
+            <BottomTabBarItem
               key={route.key}
               route={route}
-              navigation={descriptors[route.key].navigation}
-            >
-              <BottomTabItem
-                href={buildHref(route.name, route.params)}
-                route={route}
-                descriptor={descriptors[route.key]}
-                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}
-                button={options.tabBarButton}
-                icon={
-                  options.tabBarIcon ??
-                  (({ color, size }) => (
-                    <MissingIcon color={color} size={size} />
-                  ))
-                }
-                badge={options.tabBarBadge}
-                badgeStyle={options.tabBarBadgeStyle}
-                label={label}
-                showLabel={tabBarShowLabel}
-                labelVisibilityMode={tabBarLabelVisibilityMode}
-                labelStyle={options.tabBarLabelStyle}
-                iconStyle={options.tabBarIconStyle}
-                style={[
-                  sidebar
-                    ? {
-                        marginVertical: hasHorizontalLabels
-                          ? tabBarVariant === 'material'
-                            ? 0
-                            : 1
-                          : spacing / 2,
-                      }
-                    : styles.bottomItem,
-                  options.tabBarItemStyle,
-                ]}
-              />
-            </NavigationProvider>
+              descriptor={descriptors[route.key]}
+              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}
+              tabBarShowLabel={tabBarShowLabel}
+              tabBarLabelVisibilityMode={tabBarLabelVisibilityMode}
+            />
           );
         })}
       </View>
@@ -502,6 +447,132 @@ export function BottomTabBar({
   );
 }
 
+type BottomTabBarItemProps = {
+  route: TabNavigationState<ParamListBase>['routes'][number];
+  descriptor: BottomTabDescriptor;
+  navigation: BottomTabBarProps['navigation'];
+  navigatorKey: string;
+  href: string | undefined;
+  focused: boolean;
+  label: React.ComponentProps<typeof BottomTabItem>['label'];
+  accessibilityLabel: string | undefined;
+  hasHorizontalLabels: boolean;
+  compact: boolean;
+  sidebar: boolean;
+  tabBarVariant: Variant;
+  spacing: number;
+  tabBarActiveTintColor: string | undefined;
+  tabBarInactiveTintColor: string | undefined;
+  tabBarActiveBackgroundColor: string | undefined;
+  tabBarInactiveBackgroundColor: string | undefined;
+  tabBarShowLabel: boolean | undefined;
+  tabBarLabelVisibilityMode: LabelVisibilityMode | undefined;
+};
+
+const BottomTabBarItem = React.memo(function BottomTabBarItem({
+  route,
+  descriptor,
+  navigation,
+  navigatorKey,
+  href,
+  focused,
+  label,
+  accessibilityLabel,
+  hasHorizontalLabels,
+  compact,
+  sidebar,
+  tabBarVariant,
+  spacing,
+  tabBarActiveTintColor,
+  tabBarInactiveTintColor,
+  tabBarActiveBackgroundColor,
+  tabBarInactiveBackgroundColor,
+  tabBarShowLabel,
+  tabBarLabelVisibilityMode,
+}: BottomTabBarItemProps) {
+  const { options } = descriptor;
+
+  const onPress = () => {
+    const event = navigation.emit({
+      type: 'tabPress',
+      target: route.key,
+      canPreventDefault: true,
+      data: {
+        behavior: {
+          scrollToTop:
+            focused &&
+            options.tabBarRepeatedPressBehavior?.scrollToTop !== false,
+          popToTop:
+            focused && options.tabBarRepeatedPressBehavior?.popToTop !== false,
+        },
+      },
+    });
+
+    if (!focused && !event.defaultPrevented) {
+      navigation.dispatch({
+        ...CommonActions.navigate(route.name, route.params),
+        target: navigatorKey,
+      });
+    }
+  };
+
+  const onLongPress = () => {
+    navigation.emit({
+      type: 'tabLongPress',
+      target: route.key,
+    });
+  };
+
+  return (
+    <NavigationProvider route={route} navigation={descriptor.navigation}>
+      <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}
+        button={options.tabBarButton}
+        icon={
+          options.tabBarIcon ??
+          (({ color, size }) => <MissingIcon color={color} size={size} />)
+        }
+        badge={options.tabBarBadge}
+        badgeStyle={options.tabBarBadgeStyle}
+        label={label}
+        showLabel={tabBarShowLabel}
+        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

@@ -140,6 +140,10 @@ type Props = {
    * Style object for the label element.
    */
   labelStyle?: StyleProp<TextStyle>;
+  /**
+   * Size of the icon.
+   */
+  iconSize?: number;
   /**
    * Style object for the icon element.
    */
@@ -186,6 +190,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) {
@@ -300,6 +305,7 @@ export function BottomTabItem({
         route={route}
         variant={variant}
         size={compact ? 'compact' : 'regular'}
+        iconSize={iconSize}
         badge={badge}
         badgeStyle={badgeStyle}
         activeOpacity={activeOpacity}

package/src/views/BottomTabView.tsx

@@ -5,6 +5,7 @@ import {
   Screen,
 } from '@react-navigation/elements';
 import {
+  type NavigationRoute,
   type ParamListBase,
   StackActions,
   type TabNavigationState,
@@ -19,6 +20,7 @@ import {
 } from '../TransitionConfigs/TransitionPresets';
 import type {
   BottomTabBarProps,
+  BottomTabDescriptor,
   BottomTabDescriptorMap,
   BottomTabHeaderProps,
   BottomTabNavigationConfig,
@@ -283,12 +285,7 @@ export function BottomTabView(props: Props) {
       >
         {routes.map((route, index) => {
           const descriptor = descriptors[route.key];
-          const {
-            lazy = true,
-            animation = 'none',
-            sceneStyleInterpolator = NAMED_TRANSITIONS_PRESETS[animation]
-              .sceneStyleInterpolator,
-          } = descriptor.options;
+          const { lazy = true } = descriptor.options;
           const isFocused = state.index === index;
           const isPreloaded = state.preloadedRouteKeys.includes(route.key);
 
@@ -302,73 +299,23 @@ export function BottomTabView(props: Props) {
             return null;
           }
 
-          const {
-            freezeOnBlur,
-            header = ({ layout, options }: BottomTabHeaderProps) => (
-              <Header
-                {...options}
-                layout={layout}
-                title={getHeaderTitle(options, route.name)}
-              />
-            ),
-            headerShown,
-            headerStatusBarHeight,
-            headerTransparent,
-            sceneStyle: customSceneStyle,
-          } = descriptor.options;
-
-          const { sceneStyle } =
-            sceneStyleInterpolator?.({
-              current: {
-                progress: tabAnims[route.key],
-              },
-            }) ?? {};
-
-          const animationEnabled = hasAnimation(descriptor.options);
           const isAnimatingRoute =
             lastUpdate.animating &&
             (lastUpdate.previous === route.key ||
               lastUpdate.current === route.key);
 
-          const activityState = isFocused
-            ? STATE_ON_TOP // the screen is on top after the transition
-            : animationEnabled && isAnimatingRoute
-              ? STATE_TRANSITIONING_OR_BELOW_TOP // screen visible during transition
-              : STATE_INACTIVE;
-
           return (
-            <MaybeScreen
+            <TabScene
               key={route.key}
-              style={[StyleSheet.absoluteFill, { zIndex: isFocused ? 0 : -1 }]}
-              active={activityState}
-              enabled={detachInactiveScreens}
-              freezeOnBlur={freezeOnBlur}
-              shouldFreeze={activityState === STATE_INACTIVE && !isPreloaded}
-              pointerEvents={isFocused ? 'box-none' : 'none'}
-            >
-              <BottomTabBarHeightContext.Provider
-                value={tabBarPosition === 'bottom' ? tabBarHeight : 0}
-              >
-                <Screen
-                  focused={isFocused}
-                  route={descriptor.route}
-                  navigation={descriptor.navigation}
-                  headerShown={headerShown}
-                  headerStatusBarHeight={headerStatusBarHeight}
-                  headerTransparent={headerTransparent}
-                  header={header({
-                    layout: dimensions,
-                    route: descriptor.route,
-                    navigation:
-                      descriptor.navigation as BottomTabNavigationProp<ParamListBase>,
-                    options: descriptor.options,
-                  })}
-                  style={[customSceneStyle, animationEnabled && sceneStyle]}
-                >
-                  {descriptor.render()}
-                </Screen>
-              </BottomTabBarHeightContext.Provider>
-            </MaybeScreen>
+              route={route}
+              descriptor={descriptor}
+              isFocused={isFocused}
+              isPreloaded={isPreloaded}
+              isAnimatingRoute={isAnimatingRoute}
+              tabAnimation={tabAnims[route.key]}
+              tabBarHeight={tabBarPosition === 'bottom' ? tabBarHeight : 0}
+              detachInactiveScreens={detachInactiveScreens}
+            />
           );
         })}
       </MaybeScreenContainer>
@@ -379,6 +326,93 @@ export function BottomTabView(props: Props) {
   );
 }
 
+type TabSceneProps = {
+  route: NavigationRoute<ParamListBase, string>;
+  descriptor: BottomTabDescriptor;
+  isFocused: boolean;
+  isPreloaded: boolean;
+  isAnimatingRoute: boolean;
+  tabAnimation: Animated.Value;
+  tabBarHeight: number;
+  detachInactiveScreens: boolean;
+};
+
+const TabScene = React.memo(function TabScene({
+  route,
+  descriptor,
+  isFocused,
+  isPreloaded,
+  isAnimatingRoute,
+  tabAnimation,
+  tabBarHeight,
+  detachInactiveScreens,
+}: TabSceneProps) {
+  const {
+    animation = 'none',
+    sceneStyleInterpolator = NAMED_TRANSITIONS_PRESETS[animation]
+      .sceneStyleInterpolator,
+    freezeOnBlur,
+    header = ({ layout, options }: BottomTabHeaderProps) => (
+      <Header
+        {...options}
+        layout={layout}
+        title={getHeaderTitle(options, route.name)}
+      />
+    ),
+    headerShown,
+    headerStatusBarHeight,
+    headerTransparent,
+    sceneStyle: customSceneStyle,
+  } = descriptor.options;
+
+  const { sceneStyle } =
+    sceneStyleInterpolator?.({
+      current: {
+        progress: tabAnimation,
+      },
+    }) ?? {};
+
+  const animationEnabled = hasAnimation(descriptor.options);
+
+  const activityState = isFocused
+    ? STATE_ON_TOP // the screen is on top after the transition
+    : animationEnabled && isAnimatingRoute
+      ? STATE_TRANSITIONING_OR_BELOW_TOP // screen visible during transition
+      : STATE_INACTIVE;
+
+  return (
+    <MaybeScreen
+      style={[StyleSheet.absoluteFill, { zIndex: isFocused ? 0 : -1 }]}
+      active={activityState}
+      enabled={detachInactiveScreens}
+      freezeOnBlur={freezeOnBlur}
+      shouldFreeze={activityState === STATE_INACTIVE && !isPreloaded}
+      pointerEvents={isFocused ? 'box-none' : 'none'}
+    >
+      <BottomTabBarHeightContext.Provider value={tabBarHeight}>
+        <Screen
+          focused={isFocused}
+          route={descriptor.route}
+          navigation={descriptor.navigation}
+          headerShown={headerShown}
+          headerStatusBarHeight={headerStatusBarHeight}
+          headerTransparent={headerTransparent}
+          header={header({
+            layout: SafeAreaProviderCompat.initialMetrics.frame,
+            route: descriptor.route,
+            navigation:
+              descriptor.navigation as BottomTabNavigationProp<ParamListBase>,
+            options: descriptor.options,
+          })}
+          style={[customSceneStyle, animationEnabled && sceneStyle]}
+        >
+          {descriptor.render()}
+        </Screen>
+      </BottomTabBarHeightContext.Provider>
+    </MaybeScreen>
+  );
+});
+
 const styles = StyleSheet.create({
   screens: {
     flex: 1,