feat(iOS): Add support for UINavigationBackButtonDisplayMode

android/src/main/java/com/swmansion/rnscreens/ScreenStackHeaderConfigViewManager.kt

@@ -201,4 +201,8 @@ class ScreenStackHeaderConfigViewManager : ViewGroupManager<ScreenStackHeaderCon
     override fun setDisableBackButtonMenu(view: ScreenStackHeaderConfig?, value: Boolean) {
         logNotAvailable("disableBackButtonMenu")
     }
+
+    override fun setBackButtonDisplayMode(view: ScreenStackHeaderConfig?, value: String?) {
+        logNotAvailable("backButtonDisplayMode")
+    }
 }

android/src/paper/java/com/facebook/react/viewmanagers/RNSScreenStackHeaderConfigManagerDelegate.java

@@ -91,6 +91,9 @@ public void setProperty(T view, String propName, @Nullable Object value) {
       case "disableBackButtonMenu":
         mViewManager.setDisableBackButtonMenu(view, value == null ? false : (boolean) value);
         break;
+      case "backButtonDisplayMode":
+        mViewManager.setBackButtonDisplayMode(view, (String) value);
+        break;
       case "hideBackButton":
         mViewManager.setHideBackButton(view, value == null ? false : (boolean) value);
         break;

android/src/paper/java/com/facebook/react/viewmanagers/RNSScreenStackHeaderConfigManagerInterface.java

@@ -36,6 +36,7 @@ public interface RNSScreenStackHeaderConfigManagerInterface<T extends View> {
   void setTitleFontWeight(T view, @Nullable String value);
   void setTitleColor(T view, @Nullable Integer value);
   void setDisableBackButtonMenu(T view, boolean value);
+  void setBackButtonDisplayMode(T view, @Nullable String value);
   void setHideBackButton(T view, boolean value);
   void setBackButtonInCustomView(T view, boolean value);
   void setTopInsetEnabled(T view, boolean value);

guides/GUIDE_FOR_LIBRARY_AUTHORS.md

@@ -445,6 +445,10 @@ Controls whether the stack should be in `rtl` or `ltr` form.
 
 Boolean indicating whether to show the menu on longPress of iOS >= 14 back button.
 
+### `backButtonDisplayMode` (iOS only)
+
+Enum value indicating display mode of **default** back button. It works on iOS >= 14, and is used only when none of:  `backTitleFontFamily`, `backTitleFontSize`, `disableBackButtonMenu` or `backTitle` is set. Otherwise, when the button is customized, under the hood we use iOS native `backButtonItem` which overrides `backButtonDisplayMode`. Read more [#2123](https://github.com/software-mansion/react-native-screens/pull/2123).
+
 ### `hidden`
 
 When set to `true` the header will be hidden while the parent `Screen` is on the top of the stack. The default value is `false`.

ios/RNSConvert.h

@@ -6,6 +6,12 @@ namespace react = facebook::react;
 
 @interface RNSConvert : NSObject
 
++ (UISemanticContentAttribute)UISemanticContentAttributeFromCppEquivalent:
+    (react::RNSScreenStackHeaderConfigDirection)direction;
+
++ (UINavigationItemBackButtonDisplayMode)UINavigationItemBackButtonDisplayModeFromCppEquivalent:
+    (react::RNSScreenStackHeaderConfigBackButtonDisplayMode)backButtonDisplayMode;
+
 + (RNSScreenStackPresentation)RNSScreenStackPresentationFromCppEquivalent:
     (react::RNSScreenStackPresentation)stackPresentation;
 

ios/RNSConvert.mm

@@ -3,6 +3,30 @@
 #ifdef RCT_NEW_ARCH_ENABLED
 @implementation RNSConvert
 
++ (UISemanticContentAttribute)UISemanticContentAttributeFromCppEquivalent:
+    (react::RNSScreenStackHeaderConfigDirection)direction
+{
+  switch (direction) {
+    case react::RNSScreenStackHeaderConfigDirection::Rtl:
+      return UISemanticContentAttributeForceRightToLeft;
+    case react::RNSScreenStackHeaderConfigDirection::Ltr:
+      return UISemanticContentAttributeForceLeftToRight;
+  }
+}
+
++ (UINavigationItemBackButtonDisplayMode)UINavigationItemBackButtonDisplayModeFromCppEquivalent:
+    (react::RNSScreenStackHeaderConfigBackButtonDisplayMode)backButtonDisplayMode
+{
+  switch (backButtonDisplayMode) {
+    case react::RNSScreenStackHeaderConfigBackButtonDisplayMode::Default:
+      return UINavigationItemBackButtonDisplayModeDefault;
+    case react::RNSScreenStackHeaderConfigBackButtonDisplayMode::Generic:
+      return UINavigationItemBackButtonDisplayModeGeneric;
+    case react::RNSScreenStackHeaderConfigBackButtonDisplayMode::Minimal:
+      return UINavigationItemBackButtonDisplayModeMinimal;
+  }
+}
+
 + (RNSScreenStackPresentation)RNSScreenStackPresentationFromCppEquivalent:
     (react::RNSScreenStackPresentation)stackPresentation
 {

ios/RNSScreenStackHeaderConfig.h

@@ -55,6 +55,7 @@
 @property (nonatomic) BOOL translucent;
 @property (nonatomic) BOOL backButtonInCustomView;
 @property (nonatomic) UISemanticContentAttribute direction;
+@property (nonatomic) UINavigationItemBackButtonDisplayMode backButtonDisplayMode;
 
 + (void)willShowViewController:(UIViewController *)vc
                       animated:(BOOL)animated
@@ -70,5 +71,6 @@
 
 + (UIBlurEffectStyle)UIBlurEffectStyle:(id)json;
 + (UISemanticContentAttribute)UISemanticContentAttribute:(id)json;
++ (UINavigationItemBackButtonDisplayMode)UINavigationItemBackButtonDisplayMode:(id)json;
 
 @end

ios/RNSScreenStackHeaderConfig.mm

@@ -19,6 +19,7 @@
 #import <React/RCTFont.h>
 #import <React/RCTImageLoader.h>
 #import <React/RCTImageSource.h>
+#import "RNSConvert.h"
 #import "RNSScreen.h"
 #import "RNSScreenStackHeaderConfig.h"
 #import "RNSSearchBar.h"
@@ -513,6 +514,10 @@ + (void)updateViewController:(UIViewController *)vc
 
   auto isBackButtonCustomized = !isBackTitleBlank || config.disableBackButtonMenu;
 
+  if (@available(iOS 14.0, *)) {
+    prevItem.backButtonDisplayMode = config.backButtonDisplayMode;
+  }
+
   if (config.isBackTitleVisible) {
     if ((config.backTitleFontFamily &&
          // While being used by react-navigation, the `backTitleFontFamily` will
@@ -786,26 +791,16 @@ - (void)prepareForRecycle
   _initialPropsSet = NO;
 }
 
-+ (react::ComponentDescriptorProvider)componentDescriptorProvider
-{
-  return react::concreteComponentDescriptorProvider<react::RNSScreenStackHeaderConfigComponentDescriptor>();
-}
-
 - (NSNumber *)getFontSizePropValue:(int)value
 {
   if (value > 0)
     return [NSNumber numberWithInt:value];
   return nil;
 }
 
-- (UISemanticContentAttribute)getDirectionPropValue:(react::RNSScreenStackHeaderConfigDirection)direction
++ (react::ComponentDescriptorProvider)componentDescriptorProvider
 {
-  switch (direction) {
-    case react::RNSScreenStackHeaderConfigDirection::Rtl:
-      return UISemanticContentAttributeForceRightToLeft;
-    case react::RNSScreenStackHeaderConfigDirection::Ltr:
-      return UISemanticContentAttributeForceLeftToRight;
-  }
+  return react::concreteComponentDescriptorProvider<react::RNSScreenStackHeaderConfigComponentDescriptor>();
 }
 
 - (void)updateProps:(react::Props::Shared const &)props oldProps:(react::Props::Shared const &)oldProps
@@ -852,9 +847,11 @@ - (void)updateProps:(react::Props::Shared const &)props oldProps:(react::Props::
   _backTitleFontSize = [self getFontSizePropValue:newScreenProps.backTitleFontSize];
   _hideBackButton = newScreenProps.hideBackButton;
   _disableBackButtonMenu = newScreenProps.disableBackButtonMenu;
+  _backButtonDisplayMode =
+      [RNSConvert UINavigationItemBackButtonDisplayModeFromCppEquivalent:newScreenProps.backButtonDisplayMode];
 
   if (newScreenProps.direction != oldScreenProps.direction) {
-    _direction = [self getDirectionPropValue:newScreenProps.direction];
+    _direction = [RNSConvert UISemanticContentAttributeFromCppEquivalent:newScreenProps.direction];
   }
 
   _backTitleVisible = newScreenProps.backTitleVisible;
@@ -945,7 +942,9 @@ - (UIView *)view
 RCT_EXPORT_VIEW_PROPERTY(hideShadow, BOOL)
 RCT_EXPORT_VIEW_PROPERTY(backButtonInCustomView, BOOL)
 RCT_EXPORT_VIEW_PROPERTY(disableBackButtonMenu, BOOL)
-// `hidden` is an UIView property, we need to use different name internally
+RCT_EXPORT_VIEW_PROPERTY(
+    backButtonDisplayMode,
+    UINavigationItemBackButtonDisplayMode) // `hidden` is an UIView property, we need to use different name internally
 RCT_REMAP_VIEW_PROPERTY(hidden, hide, BOOL)
 RCT_EXPORT_VIEW_PROPERTY(translucent, BOOL)
 
@@ -1002,6 +1001,16 @@ + (NSMutableDictionary *)blurEffectsForIOSVersion
     UISemanticContentAttributeUnspecified,
     integerValue)
 
+RCT_ENUM_CONVERTER(
+    UINavigationItemBackButtonDisplayMode,
+    (@{
+      @"default" : @(UINavigationItemBackButtonDisplayModeDefault),
+      @"generic" : @(UINavigationItemBackButtonDisplayModeGeneric),
+      @"minimal" : @(UINavigationItemBackButtonDisplayModeMinimal),
+    }),
+    UINavigationItemBackButtonDisplayModeDefault,
+    integerValue)
+
 RCT_ENUM_CONVERTER(UIBlurEffectStyle, ([self blurEffectsForIOSVersion]), UIBlurEffectStyleExtraLight, integerValue)
 
 @end

native-stack/README.md

@@ -79,6 +79,10 @@ String that applies `rtl` or `ltr` form to the stack. On Android, you have to ad
 
 Boolean indicating whether to show the menu on longPress of iOS >= 14 back button.
 
+#### `backButtonDisplayMode` (iOS only)
+
+Enum value indicating display mode of **default** back button. It works on iOS >= 14, and is used only when none of:  `backTitleFontFamily`, `backTitleFontSize`, `disableBackButtonMenu` or `backTitle` is set. Otherwise, when the button is customized, under the hood we use iOS native `backButtonItem` which overrides `backButtonDisplayMode`. Read more [#2123](https://github.com/software-mansion/react-native-screens/pull/2123).
+
 #### `fullScreenSwipeEnabled` (iOS only)
 
 Boolean indicating whether the swipe gesture should work on whole screen. Swiping with this option results in the same transition animation as `simple_push` by default. It can be changed to other custom animations with `customAnimationOnSwipe` prop, but default iOS swipe animation is not achievable due to usage of custom recognizer. Defaults to `false`.

src/fabric/ScreenStackHeaderConfigNativeComponent.ts

@@ -13,6 +13,8 @@ type OnAttachedEvent = Readonly<{}>;
 // eslint-disable-next-line @typescript-eslint/ban-types
 type OnDetachedEvent = Readonly<{}>;
 
+type BackButtonDisplayMode = 'minimal' | 'default' | 'generic';
+
 export interface NativeProps extends ViewProps {
   onAttached?: DirectEventHandler<OnAttachedEvent>;
   onDetached?: DirectEventHandler<OnDetachedEvent>;
@@ -39,6 +41,7 @@ export interface NativeProps extends ViewProps {
   titleFontWeight?: string;
   titleColor?: ColorValue;
   disableBackButtonMenu?: boolean;
+  backButtonDisplayMode?: WithDefault<BackButtonDisplayMode, 'default'>;
   hideBackButton?: boolean;
   backButtonInCustomView?: boolean;
   // TODO: implement this props on iOS

src/native-stack/types.tsx

@@ -112,6 +112,15 @@ export type NativeStackNavigationOptions = {
    * @platform ios
    */
   disableBackButtonMenu?: boolean;
+  /**
+   * How the back button behaves by default (when not customized). Available on iOS>=14, and is used only when none of: `backTitleFontFamily`, `backTitleFontSize`, `disableBackButtonMenu` or `backTitle` is set.
+   * The following values are currently supported (they correspond to https://developer.apple.com/documentation/uikit/uinavigationitembackbuttondisplaymode?language=objc):
+   * - "default" – show given back button previous controller title, system generic or just icon based on available space
+   * - "generic" – show given system generic or just icon based on available space
+   * - "minimal" – show just an icon
+   * @platform ios
+   */
+  backButtonDisplayMode?: ScreenStackHeaderConfigProps['backButtonDisplayMode'];
   /**
    * Whether inactive screens should be suspended from re-rendering. Defaults to `false`.
    * Defaults to `true` when `enableFreeze()` is run at the top of the application.

src/native-stack/views/HeaderConfig.tsx

@@ -27,6 +27,7 @@ export default function HeaderConfig({
   backButtonInCustomView,
   direction,
   disableBackButtonMenu,
+  backButtonDisplayMode = 'default',
   headerBackTitle,
   headerBackTitleStyle = {},
   headerBackTitleVisible = true,
@@ -120,6 +121,7 @@ export default function HeaderConfig({
       color={tintColor}
       direction={direction}
       disableBackButtonMenu={disableBackButtonMenu}
+      backButtonDisplayMode={backButtonDisplayMode}
       hidden={headerShown === false}
       hideBackButton={headerHideBackButton}
       hideShadow={headerHideShadow}

src/types.tsx

@@ -19,6 +19,7 @@ export type SearchBarCommands = {
   cancelSearch: () => void;
 };
 
+export type BackButtonDisplayMode = 'default' | 'generic' | 'minimal';
 export type StackPresentationTypes =
   | 'push'
   | 'modal'
@@ -461,6 +462,15 @@ export interface ScreenStackHeaderConfigProps extends ViewProps {
    * @platform ios
    */
   disableBackButtonMenu?: boolean;
+  /**
+   * How the back button behaves by default (when not customized). Available on iOS>=14, and is used only when none of: `backTitleFontFamily`, `backTitleFontSize`, `disableBackButtonMenu` or `backTitle` is set.
+   * The following values are currently supported (they correspond to https://developer.apple.com/documentation/uikit/uinavigationitembackbuttondisplaymode?language=objc):
+   * - "default" – show given back button previous controller title, system generic or just icon based on available space
+   * - "generic" – show given system generic or just icon based on available space
+   * - "minimal" – show just an icon
+   * @platform ios
+   */
+  backButtonDisplayMode?: BackButtonDisplayMode;
   /**
    * When set to true the header will be hidden while the parent Screen is on the top of the stack. The default value is false.
    */