@react-navigation/bottom-tabs 7.20.0 → 7.22.0

package/src/unstable/NativeScreen/types.ts

@@ -64,12 +64,9 @@ export type NativeHeaderOptions = {
    *
    * @platform ios
    */
-  headerLargeTitleStyle?: StyleProp<{
-    fontFamily?: string;
-    fontSize?: number;
-    fontWeight?: string;
-    color?: ColorValue;
-  }>;
+  headerLargeTitleStyle?: StyleProp<
+    Pick<TextStyle, 'fontFamily' | 'fontSize' | 'fontWeight' | 'color'>
+  >;
   /**
    * Style object for header. Supported properties:
    * - backgroundColor

package/src/unstable/NativeScreen/useAnimatedHeaderHeight.tsx

@@ -1,11 +1,13 @@
 import * as React from 'react';
 import type { Animated } from 'react-native';
 
-export const AnimatedHeaderHeightContext = React.createContext<
+export const AnimatedHeaderHeightContext: React.Context<
   Animated.AnimatedInterpolation<number> | undefined
->(undefined);
+> = React.createContext<Animated.AnimatedInterpolation<number> | undefined>(
+  undefined
+);
 
-export function useAnimatedHeaderHeight() {
+export function useAnimatedHeaderHeight(): Animated.AnimatedInterpolation<number> {
   const animatedValue = React.useContext(AnimatedHeaderHeightContext);
 
   if (animatedValue === undefined) {

package/src/unstable/NativeScreen/useHeaderConfig.tsx

@@ -241,19 +241,12 @@ export function useHeaderConfig({
 
   const largeTitleFontWeight = headerLargeTitleStyleFlattened.fontWeight;
 
-  const headerTitleStyleSupported: TextStyle = { color: titleColor };
-
-  if (headerTitleStyleFlattened.fontFamily != null) {
-    headerTitleStyleSupported.fontFamily = headerTitleStyleFlattened.fontFamily;
-  }
-
-  if (titleFontSize != null) {
-    headerTitleStyleSupported.fontSize = titleFontSize;
-  }
-
-  if (titleFontWeight != null) {
-    headerTitleStyleSupported.fontWeight = titleFontWeight;
-  }
+  const headerTitleStyleSupported: TextStyle = {
+    color: titleColor,
+    ...(titleFontFamily != null ? { fontFamily: titleFontFamily } : null),
+    ...(titleFontSize != null ? { fontSize: titleFontSize } : null),
+    ...(titleFontWeight != null ? { fontWeight: titleFontWeight } : null),
+  };
 
   const headerBackgroundColor =
     headerStyleFlattened.backgroundColor ??
@@ -421,7 +414,8 @@ export function useHeaderConfig({
     largeTitleColor,
     largeTitleFontFamily,
     largeTitleFontSize,
-    largeTitleFontWeight,
+    largeTitleFontWeight:
+      largeTitleFontWeight != null ? String(largeTitleFontWeight) : undefined,
     largeTitleHideShadow: headerLargeTitleShadowVisible === false,
     title: titleText,
     titleColor,

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.
    *
@@ -419,10 +548,7 @@ export type NativeBottomTabNavigationConfig = {};
 export type NativeBottomTabBarProps = {
   state: TabNavigationState<ParamListBase>;
   descriptors: NativeBottomTabDescriptorMap;
-  navigation: NavigationHelpers<
-    ParamListBase,
-    NativeBottomTabNavigationEventMap
-  >;
+  navigation: NativeBottomTabNavigationHelpers;
   insets: EdgeInsets;
 };
 

package/src/views/BottomTabBar.tsx

@@ -23,9 +23,15 @@ import {
   View,
   type ViewStyle,
 } from 'react-native';
-import { type EdgeInsets } from 'react-native-safe-area-context';
-
-import type { BottomTabBarProps, BottomTabDescriptorMap } from '../types';
+import type { EdgeInsets } from 'react-native-safe-area-context';
+
+import type {
+  BottomTabBarProps,
+  BottomTabDescriptor,
+  BottomTabDescriptorMap,
+  LabelVisibilityMode,
+  Variant,
+} from '../types';
 import { BottomTabBarHeightCallbackContext } from '../utils/BottomTabBarHeightCallbackContext';
 import { useIsKeyboardShown } from '../utils/useIsKeyboardShown';
 import { BottomTabItem } from './BottomTabItem';
@@ -175,6 +181,7 @@ export function BottomTabBar({
     tabBarVariant = 'uikit',
     tabBarStyle,
     tabBarBackground,
+    tabBarTransparent,
     tabBarActiveTintColor,
     tabBarInactiveTintColor,
     tabBarActiveBackgroundColor,
@@ -241,7 +248,7 @@ export function BottomTabBar({
         }
       });
     } else {
-      // eslint-disable-next-line @eslint-react/hooks-extra/no-direct-set-state-in-use-effect
+      // eslint-disable-next-line @eslint-react/set-state-in-effect
       setIsTabBarHidden(true);
 
       const animation =
@@ -319,7 +326,9 @@ export function BottomTabBar({
           ? styles.start
           : tabBarPosition === 'right'
             ? styles.end
-            : styles.bottom,
+            : tabBarPosition === 'top'
+              ? styles.top
+              : styles.bottom,
         (
           Platform.OS === 'web'
             ? tabBarPosition === 'right'
@@ -380,6 +389,7 @@ export function BottomTabBar({
                 paddingHorizontal: Math.max(insets.left, insets.right),
               },
             ],
+        tabBarTransparent ? styles.transparent : null,
         tabBarStyle,
       ]}
       pointerEvents={isTabBarHidden ? 'none' : 'auto'}
@@ -396,38 +406,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 +422,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 +451,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,
@@ -513,12 +588,27 @@ const styles = StyleSheet.create({
     bottom: 0,
     end: 0,
   },
+  top: {
+    start: 0,
+    end: 0,
+    top: 0,
+    elevation: 8,
+  },
   bottom: {
     start: 0,
     end: 0,
     bottom: 0,
     elevation: 8,
   },
+  transparent: {
+    position: 'absolute',
+    backgroundColor: 'transparent',
+    borderTopWidth: 0,
+    borderBottomWidth: 0,
+    borderLeftWidth: 0,
+    borderRightWidth: 0,
+    elevation: 0,
+  },
   bottomContent: {
     flex: 1,
     flexDirection: 'row',

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}
@@ -319,7 +325,7 @@ export function BottomTabItem({
     ? activeBackgroundColor
     : inactiveBackgroundColor;
 
-  const { flex } = StyleSheet.flatten(style || {});
+  const flex = StyleSheet.flatten(style)?.flex;
   const borderRadius =
     variant === 'material'
       ? horizontal
@@ -335,7 +341,10 @@ export function BottomTabItem({
         // Clip ripple effect on Android
         {
           borderRadius,
-          overflow: variant === 'material' ? 'hidden' : 'visible',
+          overflow:
+            Platform.OS === 'android' && variant === 'material'
+              ? 'hidden'
+              : 'visible',
         },
         style,
       ]}