@react-navigation/bottom-tabs 7.19.2 → 7.21.0

package/src/unstable/types.tsx

@@ -28,8 +28,22 @@ export type NativeBottomTabNavigationEventMap = {
    * Event which fires on tapping on the tab in the tab bar.
    *
    * Use the `tabBarSelectionEnabled: false` option to prevent the tab from being selected.
-   */
-  tabPress: { data: undefined; canPreventDefault: false };
+   * The `data` object contains the following properties:
+   * - `origin`: always `native`.
+   * - `behavior`: specifies how consumers should handle the tab press:
+   *   - `scrollToTop`: whether the content should scroll to top.
+   *   - `popToTop`: whether a nested stack should pop to top.
+   */
+  tabPress: {
+    data: {
+      origin: 'native';
+      behavior: {
+        scrollToTop: boolean;
+        popToTop: boolean;
+      };
+    };
+    canPreventDefault: false;
+  };
   /**
    * Event which fires when a transition animation starts.
    */
@@ -87,8 +101,6 @@ type IconImage = {
    * Disabling will keep the image's original colors.
    *
    * Defaults to `true`.
-   *
-   * @platform ios
    */
   tinted?: boolean;
 };
@@ -104,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.
@@ -116,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
    *
@@ -172,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.
    */
@@ -214,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.
    *
@@ -253,6 +378,21 @@ export type NativeBottomTabNavigationOptions = NativeHeaderOptions & {
    */
   tabBarSelectionEnabled?: boolean;
 
+  /**
+   * Behavior when pressing the tab in the tab bar while it's already focused.
+   *
+   * - `scrollToTop`: scroll the first scroll view in the screen to top
+   * - `popToTop`: pop a nested stack to its first screen
+   *
+   * Both default to `true`.
+   */
+  tabBarRepeatedPressBehavior?:
+    | {
+        scrollToTop?: boolean;
+        popToTop?: boolean;
+      }
+    | undefined;
+
   /**
    * Blur effect applied to the tab bar when tab screen is selected.
    *
@@ -318,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,28 +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,
-            });
-
-            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
@@ -434,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>
@@ -492,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}