@react-navigation/native-stack 7.3.27 → 7.4.0

package/src/types.tsx

@@ -12,6 +12,7 @@ import type {
   Theme,
 } from '@react-navigation/native';
 import type {
+  ColorValue,
   ImageSourcePropType,
   StyleProp,
   TextStyle,
@@ -20,6 +21,7 @@ import type {
 import type {
   ScreenProps,
   ScreenStackHeaderConfigProps,
+  ScrollEdgeEffect,
   SearchBarProps,
 } from 'react-native-screens';
 
@@ -114,7 +116,7 @@ export type NativeStackHeaderProps = {
   navigation: NativeStackNavigationProp<ParamListBase>;
 };
 
-export type NativeStackHeaderRightProps = {
+export type NativeStackHeaderItemProps = {
   /**
    * Tint color for the header.
    */
@@ -125,10 +127,10 @@ export type NativeStackHeaderRightProps = {
   canGoBack?: boolean;
 };
 
-export type NativeStackHeaderLeftProps = NativeStackHeaderRightProps & {
+export type NativeStackHeaderBackProps = NativeStackHeaderItemProps & {
   /**
    * Label text for the button. Usually the title of the previous screen.
-   * By default, this is only shown on iOS.
+   * By default, this is only shown on iOS 18.
    */
   label?: string;
   /**
@@ -137,6 +139,16 @@ export type NativeStackHeaderLeftProps = NativeStackHeaderRightProps & {
   href?: string;
 };
 
+/**
+ * @deprecated Use `NativeStackHeaderBackProps` instead.
+ */
+export type NativeStackHeaderLeftProps = NativeStackHeaderBackProps;
+
+/**
+ * @deprecated Use `NativeStackHeaderItemProps` instead.
+ */
+export type NativeStackHeaderRightProps = NativeStackHeaderItemProps;
+
 export type NativeStackNavigationOptions = {
   /**
    * String that can be displayed in the header as a fallback for `headerTitle`.
@@ -281,12 +293,36 @@ export type NativeStackNavigationOptions = {
   /**
    * Function which returns a React Element to display on the left side of the header.
    * This replaces the back button. See `headerBackVisible` to show the back button along side left element.
+   * Will be overriden by `headerLeftItems` on iOS.
    */
-  headerLeft?: (props: NativeStackHeaderLeftProps) => React.ReactNode;
+  headerLeft?: (props: NativeStackHeaderBackProps) => React.ReactNode;
   /**
    * Function which returns a React Element to display on the right side of the header.
+   * Will be overriden by `headerRightItems` on iOS.
    */
-  headerRight?: (props: NativeStackHeaderRightProps) => React.ReactNode;
+  headerRight?: (props: NativeStackHeaderItemProps) => React.ReactNode;
+  /**
+   * Function which returns an array of items to display as on the left side of the header.
+   * Overrides `headerLeft`.
+   *
+   * This is an unstable API and might change in the future.
+   *
+   * @platform ios
+   */
+  unstable_headerLeftItems?: (
+    props: NativeStackHeaderItemProps
+  ) => NativeStackHeaderItem[];
+  /**
+   * Function which returns an array of items to display as on the right side of the header.
+   * Overrides `headerRight`.
+   *
+   * This is an unstable API and might change in the future.
+   *
+   * @platform ios
+   */
+  unstable_headerRightItems?: (
+    props: NativeStackHeaderItemProps
+  ) => NativeStackHeaderItem[];
   /**
    * String or a function that returns a React Element to be used by the header.
    * Defaults to screen `title` or route name.
@@ -668,6 +704,24 @@ export type NativeStackNavigationOptions = {
    * Only supported on iOS and Android.
    */
   freezeOnBlur?: boolean;
+  /**
+   * 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, SearchBar)
+   * for the specifed edge of the ScrollView.
+   *
+   * When set in nested containers, i.e. ScreenStack inside BottomTabs, or the other way around,
+   * the ScrollView will use only the innermost one's config.
+   *
+   * @platform ios
+   *
+   * @supported iOS 26 or higher
+   */
+  scrollEdgeEffects?: {
+    bottom?: ScrollEdgeEffect;
+    left?: ScrollEdgeEffect;
+    right?: ScrollEdgeEffect;
+    top?: ScrollEdgeEffect;
+  };
   /**
    * Footer component that can be used alongside formSheet stack presentation style.
    *
@@ -683,6 +737,282 @@ export type NativeStackNavigationOptions = {
   unstable_sheetFooter?: () => React.ReactNode;
 };
 
+type PlatformIconShared = {
+  type: 'imageSource';
+  imageSource: ImageSourcePropType;
+};
+
+type PlatformIconIOSSfSymbol = {
+  type: 'sfSymbol';
+  name: string;
+};
+
+type PlatformIconIOS = PlatformIconIOSSfSymbol | PlatformIconShared;
+
+type SharedHeaderItem = {
+  /**
+   * Label of the item.
+   */
+  label: string;
+  /**
+   * Style for the item label.
+   */
+  labelStyle?: {
+    fontFamily?: string;
+    fontSize?: number;
+    fontWeight?: string;
+    color?: ColorValue;
+  };
+  /**
+   * Icon for the item
+   */
+  icon?: PlatformIconIOS;
+  /**
+   * The variant of the item.
+   * "prominent" only available from iOS 26.0 and later.
+   *
+   * Read more: https://developer.apple.com/documentation/uikit/uibarbuttonitem/style-swift.property
+   */
+  variant?: 'plain' | 'done' | 'prominent';
+  /**
+   * The tint color to apply to the item.
+   *
+   * Read more: https://developer.apple.com/documentation/uikit/uibarbuttonitem/tintcolor
+   */
+  tintColor?: ColorValue;
+  /**
+   * Whether the item is in a disabled state.
+   */
+  disabled?: boolean;
+  /**
+   * The width of the item.
+   *
+   * Read more: https://developer.apple.com/documentation/uikit/uibarbuttonitem/width
+   */
+  width?: number;
+  /**
+   * Whether the background this item may share with other items in the bar should be hidden.
+   * Only available from iOS 26.0 and later.
+   *
+   * Read more: https://developer.apple.com/documentation/uikit/uibarbuttonitem/hidessharedbackground
+   */
+  hidesSharedBackground?: boolean;
+  /**
+   * Whether this item can share a background with other items.
+   * Only available from iOS 26.0 and later.
+   *
+   * Read more: https://developer.apple.com/documentation/uikit/uibarbuttonitem/sharesbackground
+   */
+  sharesBackground?: boolean;
+  /**
+   * An identifier used to match items across transitions.
+   * Only available from iOS 26.0 and later.
+   *
+   * Read more: https://developer.apple.com/documentation/uikit/uibarbuttonitem/identifier
+   */
+  identifier?: string;
+  /**
+   * A badge to display on a item.
+   * Only available from iOS 26.0 and later.
+   *
+   * Read more: https://developer.apple.com/documentation/uikit/uibarbuttonitembadge
+   */
+  badge?: {
+    /**
+     * The text to display in the badge.
+     */
+    value: number | string;
+    /**
+     * Style of the badge.
+     */
+    style?: {
+      color?: ColorValue;
+      backgroundColor?: ColorValue;
+      fontFamily?: string;
+      fontSize?: number;
+      fontWeight?: string;
+    };
+  };
+  /**
+   * Accessibility label for the item.
+   */
+  accessibilityLabel?: string;
+  /**
+   * Accessibility hint for the item.
+   */
+  accessibilityHint?: string;
+};
+
+/**
+ * A button item in the header.
+ */
+export type NativeStackHeaderItemButton = SharedHeaderItem & {
+  /**
+   * Type of the item.
+   */
+  type: 'button';
+  /**
+   * Function to call when the item is pressed.
+   */
+  onPress: () => void;
+  /**
+   * Whether the item is in a selected state.
+   *
+   * Read more: https://developer.apple.com/documentation/uikit/uibarbuttonitem/isselected
+   */
+  selected?: boolean;
+};
+
+/**
+ * An action item in a menu.
+ */
+export type NativeStackHeaderItemMenuAction = {
+  type: 'action';
+  /**
+   * Label for the menu item.
+   */
+  label: string;
+  /**
+   * Icon for the menu item.
+   */
+  icon?: PlatformIconIOSSfSymbol;
+  /**
+   * Function to call when the menu item is pressed.
+   */
+  onPress: () => void;
+  /**
+   * The state of an action- or command-based menu item.
+   *
+   * Read more: https://developer.apple.com/documentation/uikit/uimenuelement/state
+   */
+  state?: 'on' | 'off' | 'mixed';
+  /**
+   * Whether to apply disabled style to the item.
+   *
+   * Read more: https://developer.apple.com/documentation/uikit/uimenuelement/attributes/disabled
+   */
+  disabled?: boolean;
+  /**
+   * Whether to apply destructive style to the item.
+   *
+   * Read more: https://developer.apple.com/documentation/uikit/uimenuelement/attributes/destructive
+   */
+  destructive?: boolean;
+  /**
+   * Whether to apply hidden style to the item.
+   *
+   * Read more: https://developer.apple.com/documentation/uikit/uimenuelement/attributes/hidden
+   */
+  hidden?: boolean;
+  /**
+   * Whether to keep the menu presented after firing the element’s action.
+   *
+   * Read more: https://developer.apple.com/documentation/uikit/uimenuelement/attributes/keepsmenupresented
+   */
+  keepsMenuPresented?: boolean;
+  /**
+   * An elaborated title that explains the purpose of the action.
+   *
+   * On iOS, the system displays this title in the discoverability heads-up display (HUD).
+   * If this is not set, the HUD displays the title property.
+   *
+   * Read more: https://developer.apple.com/documentation/uikit/uiaction/discoverabilitytitle
+   */
+  discoverabilityLabel?: string;
+};
+
+/**
+ * A submenu item that contains other menu items.
+ */
+export type NativeStackHeaderItemMenuSubmenu = {
+  type: 'submenu';
+  /**
+   * Label for the submenu item.
+   */
+  label: string;
+  /**
+   * Icon for the submenu item.
+   */
+  icon?: PlatformIconIOSSfSymbol;
+  /**
+   * Array of menu items (actions or submenus).
+   */
+  items: NativeStackHeaderItemMenu['menu']['items'];
+};
+
+/**
+ * An item that shows a menu when pressed.
+ */
+export type NativeStackHeaderItemMenu = SharedHeaderItem & {
+  type: 'menu';
+  /**
+   * Whether the menu is a selection menu.
+   * Tapping an item in a selection menu will add a checkmark to the selected item.
+   *
+   * Read more: https://developer.apple.com/documentation/uikit/uibarbuttonitem/changesselectionasprimaryaction
+   */
+  changesSelectionAsPrimaryAction?: boolean;
+  /**
+   * Menu for the item.
+   */
+  menu: {
+    /**
+     * Optional title to show on top of the menu.
+     */
+    title?: string;
+    /**
+     * Array of menu items (actions or submenus).
+     */
+    items: (
+      | NativeStackHeaderItemMenuAction
+      | NativeStackHeaderItemMenuSubmenu
+    )[];
+  };
+};
+
+/**
+ * An item to add spacing between other items in the header.
+ */
+export type NativeStackHeaderItemSpacing = {
+  type: 'spacing';
+  /**
+   * The amount of spacing to add.
+   */
+  spacing: number;
+};
+
+/**
+ * A custom item to display any React Element in the header.
+ */
+export type NativeStackHeaderItemCustom = {
+  type: 'custom';
+  /**
+   * A React Element to display as the item.
+   */
+  element: React.ReactElement;
+  /**
+   * Whether the background this item may share with other items in the bar should be hidden.
+   * Only available from iOS 26.0 and later.
+   *
+   * Read more: https://developer.apple.com/documentation/uikit/uibarbuttonitem/hidessharedbackground
+   */
+  hidesSharedBackground?: boolean;
+};
+
+/**
+ * An item that can be displayed in the header.
+ * It can be a button, a menu, spacing, or a custom element.
+ *
+ * On iOS 26, when showing items on the right side of the header,
+ * if the items don't fit the available space, they will be collapsed into a menu automatically.
+ * Items with `type: 'custom'` will not be included in this automatic collapsing behavior.
+ */
+export type NativeStackHeaderItem =
+  | NativeStackHeaderItemButton
+  | NativeStackHeaderItemMenu
+  | NativeStackHeaderItemSpacing
+  | NativeStackHeaderItemCustom;
+
 export type NativeStackNavigatorProps = DefaultNavigatorOptions<
   ParamListBase,
   string | undefined,

package/src/views/NativeStackView.native.tsx

@@ -132,6 +132,7 @@ const SceneView = ({
     statusBarTranslucent,
     statusBarBackgroundColor,
     unstable_sheetFooter,
+    scrollEdgeEffects,
     freezeOnBlur,
     contentStyle,
   } = options;
@@ -277,6 +278,7 @@ const SceneView = ({
     headerHeight,
     headerShown: header !== undefined ? false : headerShown,
     headerTopInsetEnabled,
+    headerTransparent,
     headerBack,
   });
 
@@ -334,6 +336,12 @@ const SceneView = ({
           nativeBackButtonDismissalEnabled={false} // on Android
           onHeaderBackButtonClicked={onHeaderBackButtonClicked}
           preventNativeDismiss={isRemovePrevented} // on iOS
+          scrollEdgeEffects={{
+            bottom: scrollEdgeEffects?.bottom ?? 'automatic',
+            top: scrollEdgeEffects?.top ?? 'automatic',
+            left: scrollEdgeEffects?.left ?? 'automatic',
+            right: scrollEdgeEffects?.right ?? 'automatic',
+          }}
           onNativeDismissCancelled={onNativeDismissCancelled}
           // Unfortunately, because of the bug that exists on Fabric, where native event drivers
           // for Animated objects are being created after the first notifications about the header height
@@ -357,8 +365,7 @@ const SceneView = ({
 
                 if (
                   Platform.OS === 'android' &&
-                  (options.headerBackground != null ||
-                    options.headerTransparent)
+                  (headerBackground != null || headerTransparent)
                 ) {
                   // FIXME: On Android, we get 0 if the header is translucent
                   // So we set a default height in that case

package/src/views/useHeaderConfigProps.tsx

@@ -1,17 +1,32 @@
 import { getHeaderTitle, HeaderTitle } from '@react-navigation/elements';
-import { type Route, useLocale, useTheme } from '@react-navigation/native';
+import {
+  type Route,
+  type Theme,
+  useLocale,
+  useTheme,
+} from '@react-navigation/native';
+import color from 'color';
 import { Platform, StyleSheet, type TextStyle, View } from 'react-native';
 import {
+  type HeaderBarButtonItem,
+  type HeaderBarButtonItemMenuAction,
+  type HeaderBarButtonItemSubmenu,
   isSearchBarAvailableForCurrentPlatform,
   ScreenStackHeaderBackButtonImage,
   ScreenStackHeaderCenterView,
+  type ScreenStackHeaderConfigProps,
   ScreenStackHeaderLeftView,
   ScreenStackHeaderRightView,
   ScreenStackHeaderSearchBarView,
   SearchBar,
 } from 'react-native-screens';
 
-import type { NativeStackNavigationOptions } from '../types';
+import type {
+  NativeStackHeaderItem,
+  NativeStackHeaderItemMenuAction,
+  NativeStackHeaderItemMenuSubmenu,
+  NativeStackNavigationOptions,
+} from '../types';
 import { processFonts } from './FontProcessor';
 
 type Props = NativeStackNavigationOptions & {
@@ -21,6 +36,112 @@ type Props = NativeStackNavigationOptions & {
   route: Route<string>;
 };
 
+const processBarButtonItems = (
+  items: NativeStackHeaderItem[] | undefined,
+  colors: Theme['colors'],
+  fonts: Theme['fonts']
+) => {
+  return items
+    ?.map((item, index) => {
+      if (item.type === 'custom') {
+        // Handled with `ScreenStackHeaderLeftView` or `ScreenStackHeaderRightView`
+        return null;
+      }
+
+      if (item.type === 'spacing') {
+        if (item.spacing == null) {
+          throw new Error(
+            `Spacing item must have a 'spacing' property defined: ${JSON.stringify(
+              item
+            )}`
+          );
+        }
+
+        return item;
+      }
+
+      if (item.type === 'button' || item.type === 'menu') {
+        if (item.type === 'menu' && item.menu == null) {
+          throw new Error(
+            `Menu item must have a 'menu' property defined: ${JSON.stringify(
+              item
+            )}`
+          );
+        }
+
+        const { badge, label, labelStyle, ...rest } = item;
+
+        let processedItem: HeaderBarButtonItem = {
+          ...rest,
+          index,
+          title: label,
+          titleStyle: {
+            ...fonts.regular,
+            ...labelStyle,
+          },
+        };
+
+        if (processedItem.type === 'menu' && item.type === 'menu') {
+          processedItem = {
+            ...processedItem,
+            menu: {
+              ...processedItem.menu,
+              items: item.menu.items.map(getMenuItem),
+            },
+          };
+        }
+
+        if (badge) {
+          const badgeBackgroundColor =
+            badge.style?.backgroundColor ?? colors.notification;
+          const badgeTextColor = color(badgeBackgroundColor).isLight()
+            ? 'black'
+            : 'white';
+
+          processedItem = {
+            ...processedItem,
+            badge: {
+              ...badge,
+              value: String(badge.value),
+              style: {
+                backgroundColor: badgeBackgroundColor,
+                color: badgeTextColor,
+                ...fonts.regular,
+                ...badge.style,
+              },
+            },
+          };
+        }
+
+        return processedItem;
+      }
+
+      throw new Error(
+        `Invalid item type: ${JSON.stringify(item)}. Valid types are 'button', 'menu', 'custom' and 'spacing'.`
+      );
+    })
+    .filter((item) => item != null);
+};
+
+const getMenuItem = (
+  item: NativeStackHeaderItemMenuAction | NativeStackHeaderItemMenuSubmenu
+): HeaderBarButtonItemMenuAction | HeaderBarButtonItemSubmenu => {
+  const { label, ...rest } = item;
+
+  if (rest.type === 'submenu') {
+    return {
+      ...rest,
+      title: label,
+      items: rest.items.map(getMenuItem),
+    };
+  }
+
+  return {
+    ...rest,
+    title: label,
+  };
+};
+
 export function useHeaderConfigProps({
   headerBackImageSource,
   headerBackButtonDisplayMode,
@@ -49,7 +170,9 @@ export function useHeaderConfigProps({
   headerBack,
   route,
   title,
-}: Props) {
+  unstable_headerLeftItems: headerLeftItems,
+  unstable_headerRightItems: headerRightItems,
+}: Props): ScreenStackHeaderConfigProps {
   const { direction } = useLocale();
   const { colors, fonts } = useTheme();
   const tintColor =
@@ -187,11 +310,43 @@ export function useHeaderConfigProps({
 
   const isCenterViewRenderedAndroid = headerTitleAlign === 'center';
 
+  const leftItems = headerLeftItems?.({
+    tintColor,
+    canGoBack,
+  });
+
+  let rightItems = headerRightItems?.({
+    tintColor,
+    canGoBack,
+  });
+
+  if (rightItems) {
+    // iOS renders right items in reverse order
+    // So we need to reverse them here to match the order
+    rightItems = [...rightItems].reverse();
+  }
+
   const children = (
     <>
       {Platform.OS === 'ios' ? (
         <>
-          {headerLeftElement != null ? (
+          {leftItems ? (
+            leftItems.map((item, index) => {
+              if (item.type === 'custom') {
+                return (
+                  <ScreenStackHeaderLeftView
+                    // eslint-disable-next-line @eslint-react/no-array-index-key
+                    key={index}
+                    hidesSharedBackground={item.hidesSharedBackground}
+                  >
+                    {item.element}
+                  </ScreenStackHeaderLeftView>
+                );
+              }
+
+              return null;
+            })
+          ) : headerLeftElement != null ? (
             <ScreenStackHeaderLeftView>
               {headerLeftElement}
             </ScreenStackHeaderLeftView>
@@ -247,7 +402,23 @@ export function useHeaderConfigProps({
       {headerBackImageSource !== undefined ? (
         <ScreenStackHeaderBackButtonImage source={headerBackImageSource} />
       ) : null}
-      {headerRightElement != null ? (
+      {rightItems ? (
+        rightItems.map((item, index) => {
+          if (item.type === 'custom') {
+            return (
+              <ScreenStackHeaderRightView
+                // eslint-disable-next-line @eslint-react/no-array-index-key
+                key={index}
+                hidesSharedBackground={item.hidesSharedBackground}
+              >
+                {item.element}
+              </ScreenStackHeaderRightView>
+            );
+          }
+
+          return null;
+        })
+      ) : headerRightElement != null ? (
         <ScreenStackHeaderRightView>
           {headerRightElement}
         </ScreenStackHeaderRightView>
@@ -297,5 +468,7 @@ export function useHeaderConfigProps({
     topInsetEnabled: headerTopInsetEnabled,
     translucent: translucent === true,
     children,
+    headerLeftBarButtonItems: processBarButtonItems(leftItems, colors, fonts),
+    headerRightBarButtonItems: processBarButtonItems(rightItems, colors, fonts),
   } as const;
 }