From bec9396f402c9dab121315c0166367d16281f1d7 Mon Sep 17 00:00:00 2001
From: Krzysztof Ligarski <krzysztof.ligarski@swmansion.com>
Date: Thu, 16 Oct 2025 12:06:59 +0200
Subject: [PATCH 1/8] introduce new logic for creating back button

---
 ios/RNSScreenStackHeaderConfig.mm | 184 +++++++++++++++++++++---------
 1 file changed, 132 insertions(+), 52 deletions(-)

diff --git a/ios/RNSScreenStackHeaderConfig.mm b/ios/RNSScreenStackHeaderConfig.mm
index 578bd88c7d..82f0727832 100644
--- a/ios/RNSScreenStackHeaderConfig.mm
+++ b/ios/RNSScreenStackHeaderConfig.mm
@@ -755,67 +755,147 @@ - (void)configureBackItem:(nullable UINavigationItem *)prevItem
 
   const auto *config = self;
 
-  const auto isBackTitleBlank = [NSString rnscreens_isBlankOrNull:config.backTitle] == YES;
-  NSString *resolvedBackTitle = isBackTitleBlank ? prevItem.title : config.backTitle;
-
   // If previous screen controller was recreated (e.g. when you go back to tab with stack that has multiple screens),
   // its navigationItem may not have any information from screen's headerConfig, including the title.
-  // If this is the case, we attempt to extract the title from previous screen's config directly.
-  if (resolvedBackTitle == nil && [prevVC isKindOfClass:[RNSScreen class]]) {
+  // If this is the case, we attempt to set the title using previous screen's config directly.
+  if (prevItem.title == nil && [prevVC isKindOfClass:[RNSScreen class]]) {
     RNSScreen *prevScreen = static_cast<RNSScreen *>(prevVC);
-    resolvedBackTitle = prevScreen.screenView.findHeaderConfig.title;
+    RNSScreenStackHeaderConfig *prevConfig = prevScreen.screenView.findHeaderConfig;
+    if (prevConfig != nil) {
+      prevItem.title = prevConfig.title;
+    }
   }
 
-  prevItem.backButtonTitle = resolvedBackTitle;
-  // This has any effect only in case the `backBarButtonItem` is not set.
-  // We apply it before we configure the back item, because it might get overriden.
-  prevItem.backButtonDisplayMode = config.backButtonDisplayMode;
+  BOOL usesCustomFont =
+      (config.backTitleFontFamily &&
+       // While being used by react-navigation, the `backTitleFontFamily` will
+       // be set to "System" by default - which is the system default font.
+       // To avoid always considering the font as customized, we need to have an additional check.
+       // See: https://github.com/software-mansion/react-native-screens/pull/2105#discussion_r1565222738
+       ![config.backTitleFontFamily isEqual:@"System"]) ||
+      config.backTitleFontSize;
+
+  BOOL shouldUseCustomBackBarButtonItem = usesCustomFont || config.disableBackButtonMenu;
+  if (shouldUseCustomBackBarButtonItem) {
+    [self configureCustomBackItem:prevItem usingCustomFont:usesCustomFont];
+  } else {
+    [self configureNativeBackItem:prevItem];
+  }
+#endif
+}
 
-  if (config.isBackTitleVisible) {
-    RNSBackBarButtonItem *backBarButtonItem = [[RNSBackBarButtonItem alloc] initWithTitle:resolvedBackTitle
-                                                                                    style:UIBarButtonItemStylePlain
-                                                                                   target:nil
-                                                                                   action:nil];
-    auto shouldUseCustomBackBarButtonItem = config.disableBackButtonMenu;
-    [backBarButtonItem setMenuHidden:config.disableBackButtonMenu];
-
-    if ((config.backTitleFontFamily &&
-         // While being used by react-navigation, the `backTitleFontFamily` will
-         // be set to "System" by default - which is the system default font.
-         // To avoid always considering the font as customized, we need to have an additional check.
-         // See: https://github.com/software-mansion/react-native-screens/pull/2105#discussion_r1565222738
-         ![config.backTitleFontFamily isEqual:@"System"]) ||
-        config.backTitleFontSize) {
-      shouldUseCustomBackBarButtonItem = YES;
-      NSMutableDictionary *attrs = [NSMutableDictionary new];
-      NSNumber *size = config.backTitleFontSize ?: @17;
-      if (config.backTitleFontFamily) {
-        attrs[NSFontAttributeName] = [RCTFont updateFont:nil
-                                              withFamily:config.backTitleFontFamily
-                                                    size:size
-                                                  weight:nil
-                                                   style:nil
-                                                 variant:nil
-                                         scaleMultiplier:1.0];
-      } else {
-        attrs[NSFontAttributeName] = [UIFont boldSystemFontOfSize:[size floatValue]];
-      }
-      [RNSScreenStackHeaderConfig setTitleAttibutes:attrs forButton:backBarButtonItem];
-    }
+- (void)configureCustomBackItem:(nonnull UINavigationItem *)prevItem
+                usingCustomFont:(BOOL)usesCustomFont API_UNAVAILABLE(tvos)
+{
+  const auto *config = self;
 
-    // Prevent unnecessary assignment of backBarButtonItem if it is not customized,
-    // as assigning one will override the native behavior of automatically shortening
-    // the title to "Back" or hide the back title if there's not enough space.
-    // See: https://github.com/software-mansion/react-native-screens/issues/1589
-    if (shouldUseCustomBackBarButtonItem) {
-      prevItem.backBarButtonItem = backBarButtonItem;
-    }
+  NSString *resolvedBackTitle = nil;
+  if (@available(iOS 26, *)) {
+    resolvedBackTitle = [self resolveCustomBackItemTitleForSystemVersion26AndAboveWithPrevItem:prevItem];
   } else {
-    // back button title should be not visible next to back button,
-    // but it should still appear in back menu
-    prevItem.backButtonDisplayMode = UINavigationItemBackButtonDisplayModeMinimal;
+    resolvedBackTitle = [self resolveCustomBackItemTitleForSystemVersionPriorTo26WithPrevItem:prevItem];
   }
-#endif
+
+  RNSBackBarButtonItem *backBarButtonItem = [[RNSBackBarButtonItem alloc] initWithTitle:resolvedBackTitle
+                                                                                  style:UIBarButtonItemStylePlain
+                                                                                 target:nil
+                                                                                 action:nil];
+  [backBarButtonItem setMenuHidden:config.disableBackButtonMenu];
+
+  if (usesCustomFont) {
+    [self configureCustomFontForCustomBackButton:backBarButtonItem backItem:prevItem];
+  }
+
+  prevItem.backBarButtonItem = backBarButtonItem;
+}
+
+- (NSString *)resolveCustomBackItemTitleForSystemVersionPriorTo26WithPrevItem:(nonnull UINavigationItem *)prevItem
+{
+  const auto *config = self;
+
+  NSString *resolvedBackTitle = nil;
+  switch (config.backButtonDisplayMode) {
+    // We're unable to provide generic back button title for DisplayModeGeneric when using custom back item,
+    // that's why we fallback to DisplayModeDefault behavior.
+    case UINavigationItemBackButtonDisplayModeDefault:
+    case UINavigationItemBackButtonDisplayModeGeneric:
+      resolvedBackTitle = [NSString rnscreens_isBlankOrNull:config.backTitle] ? prevItem.title : config.backTitle;
+      break;
+
+    case UINavigationItemBackButtonDisplayModeMinimal:
+      resolvedBackTitle = nil;
+      break;
+
+    default:
+      RCTLogError(@"[RNScreens] Unsupported UINavigationItemBackButtonDisplayMode");
+      break;
+  }
+
+  return resolvedBackTitle;
+}
+
+- (NSString *)resolveCustomBackItemTitleForSystemVersion26AndAboveWithPrevItem:(nonnull UINavigationItem *)prevItem
+{
+  const auto *config = self;
+
+  NSString *resolvedBackTitle = nil;
+  switch (config.backButtonDisplayMode) {
+    case UINavigationItemBackButtonDisplayModeDefault:
+      resolvedBackTitle = [NSString rnscreens_isBlankOrNull:config.backTitle] ? nil : config.backTitle;
+      break;
+
+    // Starting from iOS 26, DisplayModeGeneric and DisplayModeMinimal behave in the same way.
+    case UINavigationItemBackButtonDisplayModeGeneric:
+    case UINavigationItemBackButtonDisplayModeMinimal:
+      resolvedBackTitle = nil;
+      break;
+
+    default:
+      RCTLogError(@"[RNScreens] Unsupported UINavigationItemBackButtonDisplayMode");
+      break;
+  }
+
+  return resolvedBackTitle;
+}
+
+- (void)configureCustomFontForCustomBackButton:(nonnull RNSBackBarButtonItem *)backBarButtonItem
+                                      backItem:(nonnull UINavigationItem *)prevItem
+{
+  const auto *config = self;
+
+  NSMutableDictionary *attrs = [NSMutableDictionary new];
+  NSNumber *size = config.backTitleFontSize ?: @17;
+  if (config.backTitleFontFamily) {
+    attrs[NSFontAttributeName] = [RCTFont updateFont:nil
+                                          withFamily:config.backTitleFontFamily
+                                                size:size
+                                              weight:nil
+                                               style:nil
+                                             variant:nil
+                                     scaleMultiplier:1.0];
+  } else {
+    attrs[NSFontAttributeName] = [UIFont boldSystemFontOfSize:[size floatValue]];
+  }
+  [RNSScreenStackHeaderConfig setTitleAttibutes:attrs forButton:backBarButtonItem];
+}
+
+- (void)configureNativeBackItem:(nonnull UINavigationItem *)prevItem API_UNAVAILABLE(tvos)
+{
+  const auto *config = self;
+
+  prevItem.backButtonDisplayMode = config.backButtonDisplayMode;
+
+  // We set `backButtonTitle` only if we want to use custom title
+  // as starting from iOS 26, the behavior differs between `title` and `backButtonTitle`:
+  // `title` is not shown in back button whereas `backButtonTitle` is.
+  if ([NSString rnscreens_isBlankOrNull:config.backTitle]) {
+    prevItem.backButtonTitle = nil;
+  } else {
+    prevItem.backButtonTitle = config.backTitle;
+  }
+
+  // Make sure that we don't use custom back button
+  prevItem.backBarButtonItem = nil;
 }
 
 - (void)applySemanticContentAttributeIfNeededToNavCtrl:(UINavigationController *)navCtrl

From b8b24948d7ecddf6d4a51daecd73d2c013f99ec7 Mon Sep 17 00:00:00 2001
From: Krzysztof Ligarski <krzysztof.ligarski@swmansion.com>
Date: Thu, 16 Oct 2025 12:10:14 +0200
Subject: [PATCH 2/8] add new cases to Test2809

---
 apps/src/tests/Test2809/index.tsx | 358 ++++++++++++++++++++++++++----
 1 file changed, 309 insertions(+), 49 deletions(-)

diff --git a/apps/src/tests/Test2809/index.tsx b/apps/src/tests/Test2809/index.tsx
index e44c724fb2..3ef0212394 100644
--- a/apps/src/tests/Test2809/index.tsx
+++ b/apps/src/tests/Test2809/index.tsx
@@ -10,45 +10,190 @@ import { createStackWithOptions } from './Shared';
 // Naming convention:
 // Enabled/Disabled - based on headerBackButtonMenu value
 // Default/Generic/Minimal - based on headerBackButtonDisplayMode value
-// DefaultText/CustomText/StyledText - based on label content
+// DefaultText/CustomText/StyledText/CustomStyledText - based on label content
 
 // headerBackButtonMenu: enabled
 // headerBackButtonDisplayMode: default
 const EnabledDefaultDefaultText = createStackWithOptions({}, {});
-const EnabledDefaultCustomText = createStackWithOptions({}, { headerBackTitle: 'Custom' });
-const EnabledDefaultStyledText = createStackWithOptions({}, { headerBackTitleStyle: {fontSize: 30} });
+const EnabledDefaultCustomText = createStackWithOptions(
+  {},
+  { headerBackTitle: 'Custom' },
+);
+const EnabledDefaultStyledText = createStackWithOptions(
+  {},
+  { headerBackTitleStyle: { fontSize: 30 } },
+);
+const EnabledDefaultCustomStyledText = createStackWithOptions(
+  {},
+  { headerBackTitle: 'Custom', headerBackTitleStyle: { fontSize: 30 } },
+);
 // headerBackButtonDisplayMode: generic
-const EnabledGenericDefaultText = createStackWithOptions({}, { headerBackButtonDisplayMode: 'generic' });
-const EnabledGenericCustomText = createStackWithOptions({}, { headerBackButtonDisplayMode: 'generic', headerBackTitle: 'Custom' });
-const EnabledGenericStyledText = createStackWithOptions({}, { headerBackButtonDisplayMode: 'generic', headerBackTitleStyle: {fontSize: 30} });
+const EnabledGenericDefaultText = createStackWithOptions(
+  {},
+  { headerBackButtonDisplayMode: 'generic' },
+);
+const EnabledGenericCustomText = createStackWithOptions(
+  {},
+  { headerBackButtonDisplayMode: 'generic', headerBackTitle: 'Custom' },
+);
+const EnabledGenericStyledText = createStackWithOptions(
+  {},
+  {
+    headerBackButtonDisplayMode: 'generic',
+    headerBackTitleStyle: { fontSize: 30 },
+  },
+);
+const EnabledGenericCustomStyledText = createStackWithOptions(
+  {},
+  {
+    headerBackButtonDisplayMode: 'generic',
+    headerBackTitle: 'Custom',
+    headerBackTitleStyle: { fontSize: 30 },
+  },
+);
 // headerBackButtonDisplayMode: generic
-const EnabledMinimalDefaultText = createStackWithOptions({}, { headerBackButtonDisplayMode: 'minimal' });
-const EnabledMinimalCustomText = createStackWithOptions({}, { headerBackButtonDisplayMode: 'minimal', headerBackTitle: 'Custom' });
-const EnabledMinimalStyledText = createStackWithOptions({}, { headerBackButtonDisplayMode: 'minimal', headerBackTitleStyle: {fontSize: 30} });
+const EnabledMinimalDefaultText = createStackWithOptions(
+  {},
+  { headerBackButtonDisplayMode: 'minimal' },
+);
+const EnabledMinimalCustomText = createStackWithOptions(
+  {},
+  { headerBackButtonDisplayMode: 'minimal', headerBackTitle: 'Custom' },
+);
+const EnabledMinimalStyledText = createStackWithOptions(
+  {},
+  {
+    headerBackButtonDisplayMode: 'minimal',
+    headerBackTitleStyle: { fontSize: 30 },
+  },
+);
+const EnabledMinimalCustomStyledText = createStackWithOptions(
+  {},
+  {
+    headerBackButtonDisplayMode: 'minimal',
+    headerBackTitle: 'Custom',
+    headerBackTitleStyle: { fontSize: 30 },
+  },
+);
 
 // headerBackButtonMenu: disabled
 // headerBackButtonDisplayMode: default
-const DisabledDefaultDefaultText = createStackWithOptions({}, { headerBackButtonMenuEnabled: false });
-const DisabledDefaultCustomText = createStackWithOptions({}, { headerBackButtonMenuEnabled: false, headerBackTitle: 'Custom' });
-const DisabledDefaultStyledText = createStackWithOptions({}, { headerBackButtonMenuEnabled: false, headerBackTitleStyle: {fontSize: 30}});
+const DisabledDefaultDefaultText = createStackWithOptions(
+  {},
+  { headerBackButtonMenuEnabled: false },
+);
+const DisabledDefaultCustomText = createStackWithOptions(
+  {},
+  { headerBackButtonMenuEnabled: false, headerBackTitle: 'Custom' },
+);
+const DisabledDefaultStyledText = createStackWithOptions(
+  {},
+  {
+    headerBackButtonMenuEnabled: false,
+    headerBackTitleStyle: { fontSize: 30 },
+  },
+);
+const DisabledDefaultCustomStyledText = createStackWithOptions(
+  {},
+  {
+    headerBackButtonMenuEnabled: false,
+    headerBackTitle: 'Custom',
+    headerBackTitleStyle: { fontSize: 30 },
+  },
+);
 // headerBackButtonDisplayMode: generic
-const DisabledGenericDefaultText = createStackWithOptions({}, { headerBackButtonMenuEnabled: false, headerBackButtonDisplayMode: 'generic' });
-const DisabledGenericCustomText = createStackWithOptions({}, { headerBackButtonMenuEnabled: false, headerBackButtonDisplayMode: 'generic', headerBackTitle: 'Custom' });
-const DisabledGenericStyledText = createStackWithOptions({}, { headerBackButtonMenuEnabled: false, headerBackButtonDisplayMode: 'generic', headerBackTitleStyle: {fontSize: 30} });
+const DisabledGenericDefaultText = createStackWithOptions(
+  {},
+  {
+    headerBackButtonMenuEnabled: false,
+    headerBackButtonDisplayMode: 'generic',
+  },
+);
+const DisabledGenericCustomText = createStackWithOptions(
+  {},
+  {
+    headerBackButtonMenuEnabled: false,
+    headerBackButtonDisplayMode: 'generic',
+    headerBackTitle: 'Custom',
+  },
+);
+const DisabledGenericStyledText = createStackWithOptions(
+  {},
+  {
+    headerBackButtonMenuEnabled: false,
+    headerBackButtonDisplayMode: 'generic',
+    headerBackTitleStyle: { fontSize: 30 },
+  },
+);
+const DisabledGenericCustomStyledText = createStackWithOptions(
+  {},
+  {
+    headerBackButtonMenuEnabled: false,
+    headerBackTitle: 'Custom',
+    headerBackButtonDisplayMode: 'generic',
+    headerBackTitleStyle: { fontSize: 30 },
+  },
+);
 // headerBackButtonDisplayMode: generic
-const DisabledMinimalDefaultText = createStackWithOptions({}, { headerBackButtonMenuEnabled: false, headerBackButtonDisplayMode: 'minimal' });
-const DisabledMinimalCustomText = createStackWithOptions({}, { headerBackButtonMenuEnabled: false, headerBackButtonDisplayMode: 'minimal', headerBackTitle: 'Custom' });
-const DisabledMinimalStyledText = createStackWithOptions({}, { headerBackButtonMenuEnabled: false, headerBackButtonDisplayMode: 'minimal', headerBackTitleStyle: {fontSize: 30} });
+const DisabledMinimalDefaultText = createStackWithOptions(
+  {},
+  {
+    headerBackButtonMenuEnabled: false,
+    headerBackButtonDisplayMode: 'minimal',
+  },
+);
+const DisabledMinimalCustomText = createStackWithOptions(
+  {},
+  {
+    headerBackButtonMenuEnabled: false,
+    headerBackButtonDisplayMode: 'minimal',
+    headerBackTitle: 'Custom',
+  },
+);
+const DisabledMinimalStyledText = createStackWithOptions(
+  {},
+  {
+    headerBackButtonMenuEnabled: false,
+    headerBackButtonDisplayMode: 'minimal',
+    headerBackTitleStyle: { fontSize: 30 },
+  },
+);
+const DisabledMinimalCustomStyledText = createStackWithOptions(
+  {},
+  {
+    headerBackButtonMenuEnabled: false,
+    headerBackTitle: 'Custom',
+    headerBackButtonDisplayMode: 'minimal',
+    headerBackTitleStyle: { fontSize: 30 },
+  },
+);
 
 // Custom
-const CustomLongDefaultText = createStackWithOptions({ headerTitle: 'LongLongLongLongLong'}, {});
-const CustomDefaultTextWithLongTitle = createStackWithOptions({}, {headerTitle: 'LongLongLongLongLongLongLong'});
-const CustomLongCustomText = createStackWithOptions({}, { headerBackTitle: 'LongLongLongLongLong' });
-const CustomCustomTextWithLongTitle = createStackWithOptions({}, {headerBackTitle: 'CustomBack', headerTitle: 'LongLongLongLongLongLongLong'});
-
-const Button = ({title, onPress}: {title: string, onPress: () => void}) => (
-  <TouchableOpacity onPress={onPress} style={{alignItems:'center', padding: 3}}>
-    <Text style={{fontSize: 16}}>{title}</Text>
+const CustomLongDefaultText = createStackWithOptions(
+  { headerTitle: 'LongLongLongLongLong' },
+  {},
+);
+const CustomDefaultTextWithLongTitle = createStackWithOptions(
+  {},
+  { headerTitle: 'LongLongLongLongLongLongLong' },
+);
+const CustomLongCustomText = createStackWithOptions(
+  {},
+  { headerBackTitle: 'LongLongLongLongLong' },
+);
+const CustomCustomTextWithLongTitle = createStackWithOptions(
+  {},
+  {
+    headerBackTitle: 'CustomBack',
+    headerTitle: 'LongLongLongLongLongLongLong',
+  },
+);
+
+const Button = ({ title, onPress }: { title: string; onPress: () => void }) => (
+  <TouchableOpacity
+    onPress={onPress}
+    style={{ alignItems: 'center', padding: 3 }}>
+    <Text style={{ fontSize: 16 }}>{title}</Text>
   </TouchableOpacity>
 );
 
@@ -58,7 +203,8 @@ function Home({
   navigation: NativeStackNavigationProp<ParamListBase>;
 }) {
   return (
-    <View style={{ flex: 1, backgroundColor: 'yellow', justifyContent: 'center' }}>
+    <View
+      style={{ flex: 1, backgroundColor: 'yellow', justifyContent: 'center' }}>
       <Button
         title="EnabledDefaultDefaultText"
         onPress={() => navigation.navigate('EnabledDefaultDefaultText')}
@@ -71,6 +217,10 @@ function Home({
         title="EnabledDefaultStyledText"
         onPress={() => navigation.navigate('EnabledDefaultStyledText')}
       />
+      <Button
+        title="EnabledDefaultCustomStyledText"
+        onPress={() => navigation.navigate('EnabledDefaultCustomStyledText')}
+      />
 
       <Button
         title="EnabledGenericDefaultText"
@@ -84,6 +234,10 @@ function Home({
         title="EnabledGenericStyledText"
         onPress={() => navigation.navigate('EnabledGenericStyledText')}
       />
+      <Button
+        title="EnabledGenericCustomStyledText"
+        onPress={() => navigation.navigate('EnabledGenericCustomStyledText')}
+      />
 
       <Button
         title="EnabledMinimalDefaultText"
@@ -97,6 +251,10 @@ function Home({
         title="EnabledMinimalStyledText"
         onPress={() => navigation.navigate('EnabledMinimalStyledText')}
       />
+      <Button
+        title="EnabledMinimalCustomStyledText"
+        onPress={() => navigation.navigate('EnabledMinimalCustomStyledText')}
+      />
 
       <Button
         title="DisabledDefaultDefaultText"
@@ -110,6 +268,10 @@ function Home({
         title="DisabledDefaultStyledText"
         onPress={() => navigation.navigate('DisabledDefaultStyledText')}
       />
+      <Button
+        title="DisabledDefaultCustomStyledText"
+        onPress={() => navigation.navigate('DisabledDefaultCustomStyledText')}
+      />
 
       <Button
         title="DisabledGenericDefaultText"
@@ -123,6 +285,10 @@ function Home({
         title="DisabledGenericStyledText"
         onPress={() => navigation.navigate('DisabledGenericStyledText')}
       />
+      <Button
+        title="DisabledGenericCustomStyledText"
+        onPress={() => navigation.navigate('DisabledGenericCustomStyledText')}
+      />
 
       <Button
         title="DisabledMinimalDefaultText"
@@ -136,6 +302,10 @@ function Home({
         title="DisabledMinimalStyledText"
         onPress={() => navigation.navigate('DisabledMinimalStyledText')}
       />
+      <Button
+        title="DisabledMinimalCustomStyledText"
+        onPress={() => navigation.navigate('DisabledMinimalCustomStyledText')}
+      />
 
       <Button
         title="CustomLongDefaultText"
@@ -165,34 +335,124 @@ export default function App() {
       <Stack.Navigator screenOptions={{ headerShown: false }}>
         <Stack.Screen name="Home" component={Home} />
 
-        <Stack.Screen name="EnabledDefaultDefaultText" component={EnabledDefaultDefaultText} />
-        <Stack.Screen name="EnabledDefaultCustomText" component={EnabledDefaultCustomText} />
-        <Stack.Screen name="EnabledDefaultStyledText" component={EnabledDefaultStyledText} />
+        <Stack.Screen
+          name="EnabledDefaultDefaultText"
+          component={EnabledDefaultDefaultText}
+        />
+        <Stack.Screen
+          name="EnabledDefaultCustomText"
+          component={EnabledDefaultCustomText}
+        />
+        <Stack.Screen
+          name="EnabledDefaultStyledText"
+          component={EnabledDefaultStyledText}
+        />
+        <Stack.Screen
+          name="EnabledDefaultCustomStyledText"
+          component={EnabledDefaultCustomStyledText}
+        />
 
-        <Stack.Screen name="EnabledGenericDefaultText" component={EnabledGenericDefaultText} />
-        <Stack.Screen name="EnabledGenericCustomText" component={EnabledGenericCustomText} />
-        <Stack.Screen name="EnabledGenericStyledText" component={EnabledGenericStyledText} />
+        <Stack.Screen
+          name="EnabledGenericDefaultText"
+          component={EnabledGenericDefaultText}
+        />
+        <Stack.Screen
+          name="EnabledGenericCustomText"
+          component={EnabledGenericCustomText}
+        />
+        <Stack.Screen
+          name="EnabledGenericStyledText"
+          component={EnabledGenericStyledText}
+        />
+        <Stack.Screen
+          name="EnabledGenericCustomStyledText"
+          component={EnabledGenericCustomStyledText}
+        />
 
-        <Stack.Screen name="EnabledMinimalDefaultText" component={EnabledMinimalDefaultText} />
-        <Stack.Screen name="EnabledMinimalCustomText" component={EnabledMinimalCustomText} />
-        <Stack.Screen name="EnabledMinimalStyledText" component={EnabledMinimalStyledText} />
+        <Stack.Screen
+          name="EnabledMinimalDefaultText"
+          component={EnabledMinimalDefaultText}
+        />
+        <Stack.Screen
+          name="EnabledMinimalCustomText"
+          component={EnabledMinimalCustomText}
+        />
+        <Stack.Screen
+          name="EnabledMinimalStyledText"
+          component={EnabledMinimalStyledText}
+        />
+        <Stack.Screen
+          name="EnabledMinimalCustomStyledText"
+          component={EnabledMinimalCustomStyledText}
+        />
 
-        <Stack.Screen name="DisabledDefaultDefaultText" component={DisabledDefaultDefaultText} />
-        <Stack.Screen name="DisabledDefaultCustomText" component={DisabledDefaultCustomText} />
-        <Stack.Screen name="DisabledDefaultStyledText" component={DisabledDefaultStyledText} />
+        <Stack.Screen
+          name="DisabledDefaultDefaultText"
+          component={DisabledDefaultDefaultText}
+        />
+        <Stack.Screen
+          name="DisabledDefaultCustomText"
+          component={DisabledDefaultCustomText}
+        />
+        <Stack.Screen
+          name="DisabledDefaultStyledText"
+          component={DisabledDefaultStyledText}
+        />
+        <Stack.Screen
+          name="DisabledDefaultCustomStyledText"
+          component={DisabledDefaultCustomStyledText}
+        />
 
-        <Stack.Screen name="DisabledGenericDefaultText" component={DisabledGenericDefaultText} />
-        <Stack.Screen name="DisabledGenericCustomText" component={DisabledGenericCustomText} />
-        <Stack.Screen name="DisabledGenericStyledText" component={DisabledGenericStyledText} />
+        <Stack.Screen
+          name="DisabledGenericDefaultText"
+          component={DisabledGenericDefaultText}
+        />
+        <Stack.Screen
+          name="DisabledGenericCustomText"
+          component={DisabledGenericCustomText}
+        />
+        <Stack.Screen
+          name="DisabledGenericStyledText"
+          component={DisabledGenericStyledText}
+        />
+        <Stack.Screen
+          name="DisabledGenericCustomStyledText"
+          component={DisabledGenericCustomStyledText}
+        />
 
-        <Stack.Screen name="DisabledMinimalDefaultText" component={DisabledMinimalDefaultText} />
-        <Stack.Screen name="DisabledMinimalCustomText" component={DisabledMinimalCustomText} />
-        <Stack.Screen name="DisabledMinimalStyledText" component={DisabledMinimalStyledText} />
+        <Stack.Screen
+          name="DisabledMinimalDefaultText"
+          component={DisabledMinimalDefaultText}
+        />
+        <Stack.Screen
+          name="DisabledMinimalCustomText"
+          component={DisabledMinimalCustomText}
+        />
+        <Stack.Screen
+          name="DisabledMinimalStyledText"
+          component={DisabledMinimalStyledText}
+        />
+        <Stack.Screen
+          name="DisabledMinimalCustomStyledText"
+          component={DisabledMinimalCustomStyledText}
+        />
 
-        <Stack.Screen name="CustomLongDefaultText" component={CustomLongDefaultText} />
-        <Stack.Screen name="CustomDefaultTextWithLongTitle" component={CustomDefaultTextWithLongTitle} />
-        <Stack.Screen name="CustomLongCustomText" component={CustomLongCustomText} />
-        <Stack.Screen name="CustomCustomTextWithLongTitle" component={CustomCustomTextWithLongTitle} />
+        <Stack.Screen
+          name="CustomLongDefaultText"
+          component={CustomLongDefaultText}
+        />
+        <Stack.Screen
+          name="CustomDefaultTextWithLongTitle"
+          component={CustomDefaultTextWithLongTitle}
+        />
+        <Stack.Screen
+          name="CustomLongCustomText"
+          component={CustomLongCustomText}
+        />
+        <Stack.Screen
+          name="CustomCustomTextWithLongTitle"
+          component={CustomCustomTextWithLongTitle}
+        />
       </Stack.Navigator>
     </NavigationContainer>
   );

From 9965b8cdaede3d7f2a39063afca42f067b5228b3 Mon Sep 17 00:00:00 2001
From: Krzysztof Ligarski <krzysztof.ligarski@swmansion.com>
Date: Thu, 16 Oct 2025 12:17:43 +0200
Subject: [PATCH 3/8] add deprecation message

---
 src/types.tsx | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/src/types.tsx b/src/types.tsx
index aef6d2255b..d448449150 100644
--- a/src/types.tsx
+++ b/src/types.tsx
@@ -616,10 +616,7 @@ export interface ScreenStackHeaderConfigProps extends ViewProps {
    */
   backTitleFontSize?: number;
   /**
-   * Whether the back button title should be visible or not. Defaults to `true`.
-   *
-   * When set to `false` it works as a "kill switch": it enforces `backButtonDisplayMode=minimal` and ignores `backButtonDisplayMode`, `backTitleFontSize`, `backTitleFontFamily`, `disableBackButtonMenu`.
-   * For `backTitle` it works only in back button menu.
+   * @deprecated Setting this prop has no effect. Retained only for backward compatibility.
    *
    * @platform ios
    */

From 85e0ce45ddbd14950057bc7b5cc8940b8f63f8e8 Mon Sep 17 00:00:00 2001
From: Krzysztof Ligarski <krzysztof.ligarski@swmansion.com>
Date: Thu, 16 Oct 2025 12:36:10 +0200
Subject: [PATCH 4/8] update docs

---
 guides/GUIDE_FOR_LIBRARY_AUTHORS.md | 22 +++++++++++++++++-----
 src/types.tsx                       | 20 +++++++++++++++-----
 2 files changed, 32 insertions(+), 10 deletions(-)

diff --git a/guides/GUIDE_FOR_LIBRARY_AUTHORS.md b/guides/GUIDE_FOR_LIBRARY_AUTHORS.md
index 51f65ce95b..c279f9588a 100644
--- a/guides/GUIDE_FOR_LIBRARY_AUTHORS.md
+++ b/guides/GUIDE_FOR_LIBRARY_AUTHORS.md
@@ -523,7 +523,7 @@ Controls the color of the navigation header.
 
 ### `backTitle` (iOS only)
 
-Allows for controlling the string to be rendered next to back button. By default iOS uses the title of the previous screen.
+Allows for controlling the string to be rendered next to back button. For iOS versions prior to 26, the title of the previous screen is used as default.
 
 ### `backTitleFontFamily` (iOS only)
 
@@ -535,6 +535,8 @@ Allows for customizing font size to be used for back button title on iOS.
 
 ### `backTitleVisible` (iOS only)
 
+This prop has been **deprecated**. Setting it has no effect as native code related to this prop has been removed. Kept only for backward compatibility. Will be removed in next major release.
+
 Whether the back button title should be visible. Defaults to `true`.
 
 When set to `false` it works as a "kill switch": it enforces `backButtonDisplayMode=minimal` and ignores `backButtonDisplayMode`, `backTitleFontSize`, `backTitleFontFamily`, `disableBackButtonMenu`, and `backTitle` works only for back button menu.
@@ -553,18 +555,28 @@ Controls whether the stack should be in `rtl` or `ltr` form.
 
 ### `disableBackButtonMenu` (iOS only)
 
-Boolean indicating whether to show the menu on longPress of iOS >= 14 back button.
+Boolean indicating whether to show the menu on longPress of the back button.
 
 ### `backButtonDisplayMode` (iOS only)
 
-Enum value indicating display mode of back button. It is used only when none of: `backTitleFontFamily`, `backTitleFontSize`, `disableBackButtonMenu` and `backTitleVisible=false` is set. The `backTitleVisible` forces `backButtonDisplayMode: minimal` and omits other values. Read more [#2800](https://github.com/software-mansion/react-native-screens/pull/2800). The other props, under the hood, customize `backButtonItem` which overrides `backButtonDisplayMode`. Read more [#2123](https://github.com/software-mansion/react-native-screens/pull/2123).
+Enum value indicating display mode of back button.
 
 Possible options:
 
-- `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
+- `default` – show given back button previous controller title, system generic or just icon based on available space and OS version
+- `generic` – show given system generic or just icon based on available space and OS version
 - `minimal` – show just an icon
 
+Starting from iOS 26:
+- the `title` of the previous screen is not used as back button title,
+- `generic` display mode behaves the same as `minimal`.
+
+In order to add text to the back button on iOS 26, use `default` display mode and specify text in `backTitle` property.
+
+On iOS versions prior to 26, using `generic` display mode with `backTitleFontFamily`, `backTitleFontSize`
+or `disableBackButtonMenu` property set is not supported due to limitations in the native platform.
+In such cases, display mode will fallback to `default`.
+
 ### `headerLeftBarButtonItems` / `headerRightBarButtonsItems` (iOS only)
 
 An array of objects describing native bar button items to display on the left or right side of the header. Each item can be:
diff --git a/src/types.tsx b/src/types.tsx
index d448449150..ccb53dd41a 100644
--- a/src/types.tsx
+++ b/src/types.tsx
@@ -602,7 +602,7 @@ export interface ScreenStackHeaderConfigProps extends ViewProps {
   backgroundColor?: ColorValue;
   /**
    * Title to display in the back button.
-   * @platform ios.
+   * @platform ios
    */
   backTitle?: string;
   /**
@@ -639,18 +639,28 @@ export interface ScreenStackHeaderConfigProps extends ViewProps {
    */
   direction?: 'rtl' | 'ltr';
   /**
-   * Boolean indicating whether to show the menu on longPress of iOS >= 14 back button.
+   * Boolean indicating whether to show the menu on longPress of the back button.
    * @platform ios
    */
   disableBackButtonMenu?: boolean;
   /**
-   * How the back button behaves. It is used only when none of: `backTitleFontFamily`, `backTitleFontSize`, `disableBackButtonMenu` and `backTitleVisible=false` is set.
+   * How the back button behaves.
    * The following values are currently supported (they correspond to [UINavigationItemBackButtonDisplayMode](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
+   * - `default` – show given back button previous controller title, system generic or just icon based on available space and OS version
+   * - `generic` – show given system generic or just icon based on available space and OS version
    * - `minimal` – show just an icon
    *
+   * Starting from iOS 26:
+   * - the `title` of the previous screen is not used as back button title,
+   * - `generic` display mode behaves the same as `minimal`.
+   *
+   * In order to add text to the back button on iOS 26, use `default` display mode and specify text in `backTitle` property.
+   *
+   * On iOS versions prior to 26, using `generic` display mode with `backTitleFontFamily`, `backTitleFontSize`
+   * or `disableBackButtonMenu` property set is not supported due to limitations in the native platform.
+   * In such cases, display mode will fallback to `default`.
+   *
    * @platform ios
    */
   backButtonDisplayMode?: BackButtonDisplayMode;

From add18b3047a4ee6815c88de9e4bdcb7ab9c7721d Mon Sep 17 00:00:00 2001
From: Krzysztof Ligarski <krzysztof.ligarski@swmansion.com>
Date: Wed, 22 Oct 2025 16:58:32 +0200
Subject: [PATCH 5/8] add backButtonUseModernImplementation prop to keep
 backward compatibility

---
 guides/GUIDE_FOR_LIBRARY_AUTHORS.md           | 15 +++-
 ios/RNSScreenStackHeaderConfig.h              |  1 +
 ios/RNSScreenStackHeaderConfig.mm             | 87 +++++++++++++++++++
 .../ScreenStackHeaderConfigNativeComponent.ts |  1 +
 src/types.tsx                                 | 20 ++++-
 5 files changed, 121 insertions(+), 3 deletions(-)

diff --git a/guides/GUIDE_FOR_LIBRARY_AUTHORS.md b/guides/GUIDE_FOR_LIBRARY_AUTHORS.md
index c279f9588a..cf9d6a065b 100644
--- a/guides/GUIDE_FOR_LIBRARY_AUTHORS.md
+++ b/guides/GUIDE_FOR_LIBRARY_AUTHORS.md
@@ -523,7 +523,7 @@ Controls the color of the navigation header.
 
 ### `backTitle` (iOS only)
 
-Allows for controlling the string to be rendered next to back button. For iOS versions prior to 26, the title of the previous screen is used as default.
+Allows for controlling the string to be rendered next to back button. The title of the previous screen is used as default if `backButtonUseModernImplementation` is set to `false` or if `backButtonUseModernImplementation` is set to `true` and iOS version prior to 26 is used.
 
 ### `backTitleFontFamily` (iOS only)
 
@@ -535,7 +535,7 @@ Allows for customizing font size to be used for back button title on iOS.
 
 ### `backTitleVisible` (iOS only)
 
-This prop has been **deprecated**. Setting it has no effect as native code related to this prop has been removed. Kept only for backward compatibility. Will be removed in next major release.
+This prop has been **deprecated**. Kept only for backward compatibility, is respected only if `backButtonUseModernImplementation` is set to `false`.
 
 Whether the back button title should be visible. Defaults to `true`.
 
@@ -577,6 +577,17 @@ On iOS versions prior to 26, using `generic` display mode with `backTitleFontFam
 or `disableBackButtonMenu` property set is not supported due to limitations in the native platform.
 In such cases, display mode will fallback to `default`.
 
+If `backButtonUseModernImplementation` is set to `false`, this prop is used only when none of: `backTitleFontFamily`,
+`backTitleFontSize`, `disableBackButtonMenu` and `backTitleVisible=false` is set.
+
+### `backButtonUseModernImplementation` (iOS only)
+
+Used for backward compatibility only. Setting this prop to `false` is recommended.
+
+Uses previous implementation of native back button configuration.
+
+Default is `true`.
+
 ### `headerLeftBarButtonItems` / `headerRightBarButtonsItems` (iOS only)
 
 An array of objects describing native bar button items to display on the left or right side of the header. Each item can be:
diff --git a/ios/RNSScreenStackHeaderConfig.h b/ios/RNSScreenStackHeaderConfig.h
index dfd617b841..cb0432d962 100644
--- a/ios/RNSScreenStackHeaderConfig.h
+++ b/ios/RNSScreenStackHeaderConfig.h
@@ -58,6 +58,7 @@ NS_ASSUME_NONNULL_BEGIN
 @property (nonatomic) BOOL backButtonInCustomView;
 @property (nonatomic) UISemanticContentAttribute direction;
 @property (nonatomic) UINavigationItemBackButtonDisplayMode backButtonDisplayMode;
+@property (nonatomic) BOOL backButtonUseModernImplementation;
 @property (nonatomic) RNSBlurEffectStyle blurEffect;
 @property (nonatomic, copy, nullable) NSArray<NSDictionary<NSString *, id> *> *headerRightBarButtonItems;
 @property (nonatomic, copy, nullable) NSArray<NSDictionary<NSString *, id> *> *headerLeftBarButtonItems;
diff --git a/ios/RNSScreenStackHeaderConfig.mm b/ios/RNSScreenStackHeaderConfig.mm
index 82f0727832..332711cfdd 100644
--- a/ios/RNSScreenStackHeaderConfig.mm
+++ b/ios/RNSScreenStackHeaderConfig.mm
@@ -747,6 +747,18 @@ + (void)updateViewController:(UIViewController *)vc
 
 - (void)configureBackItem:(nullable UINavigationItem *)prevItem
                withPrevVC:(nullable UIViewController *)prevVC API_UNAVAILABLE(tvos)
+{
+  const auto *config = self;
+
+  if (config.backButtonUseModernImplementation) {
+    [self configureModernBackItem:prevItem withPrevVC:prevVC];
+  } else {
+    [self configureLegacyBackItem:prevItem withPrevVC:prevVC];
+  }
+}
+
+- (void)configureModernBackItem:(nullable UINavigationItem *)prevItem
+                     withPrevVC:(nullable UIViewController *)prevVC API_UNAVAILABLE(tvos)
 {
 #if !TARGET_OS_TV
   if (prevItem == nil) {
@@ -898,6 +910,79 @@ - (void)configureNativeBackItem:(nonnull UINavigationItem *)prevItem API_UNAVAIL
   prevItem.backBarButtonItem = nil;
 }
 
+- (void)configureLegacyBackItem:(nullable UINavigationItem *)prevItem
+                     withPrevVC:(nullable UIViewController *)prevVC API_UNAVAILABLE(tvos)
+{
+#if !TARGET_OS_TV
+  if (prevItem == nil) {
+    return;
+  }
+
+  const auto *config = self;
+
+  const auto isBackTitleBlank = [NSString rnscreens_isBlankOrNull:config.backTitle] == YES;
+  NSString *resolvedBackTitle = isBackTitleBlank ? prevItem.title : config.backTitle;
+
+  // If previous screen controller was recreated (e.g. when you go back to tab with stack that has multiple screens),
+  // its navigationItem may not have any information from screen's headerConfig, including the title.
+  // If this is the case, we attempt to extract the title from previous screen's config directly.
+  if (resolvedBackTitle == nil && [prevVC isKindOfClass:[RNSScreen class]]) {
+    RNSScreen *prevScreen = static_cast<RNSScreen *>(prevVC);
+    resolvedBackTitle = prevScreen.screenView.findHeaderConfig.title;
+  }
+
+  prevItem.backButtonTitle = resolvedBackTitle;
+  // This has any effect only in case the `backBarButtonItem` is not set.
+  // We apply it before we configure the back item, because it might get overriden.
+  prevItem.backButtonDisplayMode = config.backButtonDisplayMode;
+
+  if (config.isBackTitleVisible) {
+    RNSBackBarButtonItem *backBarButtonItem = [[RNSBackBarButtonItem alloc] initWithTitle:resolvedBackTitle
+                                                                                    style:UIBarButtonItemStylePlain
+                                                                                   target:nil
+                                                                                   action:nil];
+    auto shouldUseCustomBackBarButtonItem = config.disableBackButtonMenu;
+    [backBarButtonItem setMenuHidden:config.disableBackButtonMenu];
+
+    if ((config.backTitleFontFamily &&
+         // While being used by react-navigation, the `backTitleFontFamily` will
+         // be set to "System" by default - which is the system default font.
+         // To avoid always considering the font as customized, we need to have an additional check.
+         // See: https://github.com/software-mansion/react-native-screens/pull/2105#discussion_r1565222738
+         ![config.backTitleFontFamily isEqual:@"System"]) ||
+        config.backTitleFontSize) {
+      shouldUseCustomBackBarButtonItem = YES;
+      NSMutableDictionary *attrs = [NSMutableDictionary new];
+      NSNumber *size = config.backTitleFontSize ?: @17;
+      if (config.backTitleFontFamily) {
+        attrs[NSFontAttributeName] = [RCTFont updateFont:nil
+                                              withFamily:config.backTitleFontFamily
+                                                    size:size
+                                                  weight:nil
+                                                   style:nil
+                                                 variant:nil
+                                         scaleMultiplier:1.0];
+      } else {
+        attrs[NSFontAttributeName] = [UIFont boldSystemFontOfSize:[size floatValue]];
+      }
+      [RNSScreenStackHeaderConfig setTitleAttibutes:attrs forButton:backBarButtonItem];
+    }
+
+    // Prevent unnecessary assignment of backBarButtonItem if it is not customized,
+    // as assigning one will override the native behavior of automatically shortening
+    // the title to "Back" or hide the back title if there's not enough space.
+    // See: https://github.com/software-mansion/react-native-screens/issues/1589
+    if (shouldUseCustomBackBarButtonItem) {
+      prevItem.backBarButtonItem = backBarButtonItem;
+    }
+  } else {
+    // back button title should be not visible next to back button,
+    // but it should still appear in back menu
+    prevItem.backButtonDisplayMode = UINavigationItemBackButtonDisplayModeMinimal;
+  }
+#endif
+}
+
 - (void)applySemanticContentAttributeIfNeededToNavCtrl:(UINavigationController *)navCtrl
 {
   if ((self.direction == UISemanticContentAttributeForceLeftToRight ||
@@ -1216,6 +1301,7 @@ - (void)updateProps:(react::Props::Shared const &)props oldProps:(react::Props::
   }
 
   _backTitleVisible = newScreenProps.backTitleVisible;
+  _backButtonUseModernImplementation = newScreenProps.backButtonUseModernImplementation;
 
   // We cannot compare SharedColor because it is shared value.
   // We could compare color value, but it is more performant to just assign new value
@@ -1357,6 +1443,7 @@ - (RCTShadowView *)shadowView
 RCT_EXPORT_VIEW_PROPERTY(backButtonInCustomView, BOOL)
 RCT_EXPORT_VIEW_PROPERTY(disableBackButtonMenu, BOOL)
 RCT_EXPORT_VIEW_PROPERTY(backButtonDisplayMode, UINavigationItemBackButtonDisplayMode)
+RCT_EXPORT_VIEW_PROPERTY(backButtonUseModernImplementation, BOOL)
 RCT_REMAP_VIEW_PROPERTY(hidden, hide, BOOL) // `hidden` is an UIView property, we need to use different name internally
 RCT_EXPORT_VIEW_PROPERTY(translucent, BOOL)
 RCT_EXPORT_VIEW_PROPERTY(headerLeftBarButtonItems, NSArray)
diff --git a/src/fabric/ScreenStackHeaderConfigNativeComponent.ts b/src/fabric/ScreenStackHeaderConfigNativeComponent.ts
index 2fbbea2f1f..b6eb93190f 100644
--- a/src/fabric/ScreenStackHeaderConfigNativeComponent.ts
+++ b/src/fabric/ScreenStackHeaderConfigNativeComponent.ts
@@ -72,6 +72,7 @@ export interface NativeProps extends ViewProps {
   titleColor?: ColorValue;
   disableBackButtonMenu?: boolean;
   backButtonDisplayMode?: WithDefault<BackButtonDisplayMode, 'default'>;
+  backButtonUseModernImplementation?: WithDefault<boolean, false>;
   hideBackButton?: boolean;
   backButtonInCustomView?: boolean;
   blurEffect?: WithDefault<BlurEffect, 'none'>;
diff --git a/src/types.tsx b/src/types.tsx
index ccb53dd41a..3c410d6216 100644
--- a/src/types.tsx
+++ b/src/types.tsx
@@ -616,7 +616,12 @@ export interface ScreenStackHeaderConfigProps extends ViewProps {
    */
   backTitleFontSize?: number;
   /**
-   * @deprecated Setting this prop has no effect. Retained only for backward compatibility.
+   * @deprecated This prop is respected only if `backButtonUseModernImplementation` is set to `false`.
+   *
+   * Whether the back button title should be visible or not. Defaults to `true`.
+   *
+   * When set to `false` it works as a "kill switch": it enforces `backButtonDisplayMode=minimal` and ignores `backButtonDisplayMode`, `backTitleFontSize`, `backTitleFontFamily`, `disableBackButtonMenu`.
+   * For `backTitle` it works only in back button menu.
    *
    * @platform ios
    */
@@ -661,9 +666,22 @@ export interface ScreenStackHeaderConfigProps extends ViewProps {
    * or `disableBackButtonMenu` property set is not supported due to limitations in the native platform.
    * In such cases, display mode will fallback to `default`.
    *
+   * If `backButtonUseModernImplementation` is set to `false`, this prop is used only when none of: `backTitleFontFamily`,
+   * `backTitleFontSize`, `disableBackButtonMenu` and `backTitleVisible=false` is set.
+   *
    * @platform ios
    */
   backButtonDisplayMode?: BackButtonDisplayMode;
+  /**
+   * Setting this prop to `true` is recommended. Prop available for backward compatibility.
+   *
+   * Uses new implementation for native back button configuration.
+   *
+   * @default false
+   *
+   * @platform ios
+   */
+  backButtonUseModernImplementation?: boolean;
   /**
    * Array of UIBarButtomItems to the left side of the header.
    *

From 89f9390304bcef70106a1dc58d50297d9aa24162 Mon Sep 17 00:00:00 2001
From: Krzysztof Ligarski <krzysztof.ligarski@swmansion.com>
Date: Wed, 22 Oct 2025 17:05:53 +0200
Subject: [PATCH 6/8] (don't) handle new prop on Android

---
 .../rnscreens/ScreenStackHeaderConfigViewManager.kt        | 7 +++++++
 .../RNSScreenStackHeaderConfigManagerDelegate.java         | 3 +++
 .../RNSScreenStackHeaderConfigManagerInterface.java        | 1 +
 3 files changed, 11 insertions(+)

diff --git a/android/src/main/java/com/swmansion/rnscreens/ScreenStackHeaderConfigViewManager.kt b/android/src/main/java/com/swmansion/rnscreens/ScreenStackHeaderConfigViewManager.kt
index 080b79819e..523066266b 100644
--- a/android/src/main/java/com/swmansion/rnscreens/ScreenStackHeaderConfigViewManager.kt
+++ b/android/src/main/java/com/swmansion/rnscreens/ScreenStackHeaderConfigViewManager.kt
@@ -313,6 +313,13 @@ class ScreenStackHeaderConfigViewManager :
         logNotAvailable("backButtonDisplayMode")
     }
 
+    override fun setBackButtonUseModernImplementation(
+        view: ScreenStackHeaderConfig?,
+        value: Boolean,
+    ) {
+        logNotAvailable("backButtonUseModernImplementation")
+    }
+
     override fun setBlurEffect(
         view: ScreenStackHeaderConfig?,
         value: String?,
diff --git a/android/src/paper/java/com/facebook/react/viewmanagers/RNSScreenStackHeaderConfigManagerDelegate.java b/android/src/paper/java/com/facebook/react/viewmanagers/RNSScreenStackHeaderConfigManagerDelegate.java
index 3ef1e7a08d..db1dca705c 100644
--- a/android/src/paper/java/com/facebook/react/viewmanagers/RNSScreenStackHeaderConfigManagerDelegate.java
+++ b/android/src/paper/java/com/facebook/react/viewmanagers/RNSScreenStackHeaderConfigManagerDelegate.java
@@ -97,6 +97,9 @@ public void setProperty(T view, String propName, @Nullable Object value) {
       case "backButtonDisplayMode":
         mViewManager.setBackButtonDisplayMode(view, (String) value);
         break;
+      case "backButtonUseModernImplementation":
+        mViewManager.setBackButtonUseModernImplementation(view, value == null ? false : (boolean) value);
+        break;
       case "hideBackButton":
         mViewManager.setHideBackButton(view, value == null ? false : (boolean) value);
         break;
diff --git a/android/src/paper/java/com/facebook/react/viewmanagers/RNSScreenStackHeaderConfigManagerInterface.java b/android/src/paper/java/com/facebook/react/viewmanagers/RNSScreenStackHeaderConfigManagerInterface.java
index 0f1bc58396..99c90c6178 100644
--- a/android/src/paper/java/com/facebook/react/viewmanagers/RNSScreenStackHeaderConfigManagerInterface.java
+++ b/android/src/paper/java/com/facebook/react/viewmanagers/RNSScreenStackHeaderConfigManagerInterface.java
@@ -39,6 +39,7 @@ public interface RNSScreenStackHeaderConfigManagerInterface<T extends View>  {
   void setTitleColor(T view, @Nullable Integer value);
   void setDisableBackButtonMenu(T view, boolean value);
   void setBackButtonDisplayMode(T view, @Nullable String value);
+  void setBackButtonUseModernImplementation(T view, boolean value);
   void setHideBackButton(T view, boolean value);
   void setBackButtonInCustomView(T view, boolean value);
   void setBlurEffect(T view, @Nullable String value);

From 83237609da274badce122df336690661df127170 Mon Sep 17 00:00:00 2001
From: Krzysztof Ligarski <krzysztof.ligarski@swmansion.com>
Date: Thu, 23 Oct 2025 15:41:00 +0200
Subject: [PATCH 7/8] fix typo

---
 ios/RNSScreenStackHeaderConfig.mm | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/ios/RNSScreenStackHeaderConfig.mm b/ios/RNSScreenStackHeaderConfig.mm
index 332711cfdd..19566bc66b 100644
--- a/ios/RNSScreenStackHeaderConfig.mm
+++ b/ios/RNSScreenStackHeaderConfig.mm
@@ -319,7 +319,7 @@ + (void)setAnimatedConfig:(UIViewController *)vc withConfig:(RNSScreenStackHeade
   // font customized on the navigation item level, so nothing to do here
 }
 
-+ (void)setTitleAttibutes:(NSDictionary *)attrs forButton:(UIBarButtonItem *)button
++ (void)setTitleAttributes:(NSDictionary *)attrs forButton:(UIBarButtonItem *)button
 {
   [button setTitleTextAttributes:attrs forState:UIControlStateNormal];
   [button setTitleTextAttributes:attrs forState:UIControlStateHighlighted];
@@ -888,7 +888,7 @@ - (void)configureCustomFontForCustomBackButton:(nonnull RNSBackBarButtonItem *)b
   } else {
     attrs[NSFontAttributeName] = [UIFont boldSystemFontOfSize:[size floatValue]];
   }
-  [RNSScreenStackHeaderConfig setTitleAttibutes:attrs forButton:backBarButtonItem];
+  [RNSScreenStackHeaderConfig setTitleAttributes:attrs forButton:backBarButtonItem];
 }
 
 - (void)configureNativeBackItem:(nonnull UINavigationItem *)prevItem API_UNAVAILABLE(tvos)
@@ -965,7 +965,7 @@ - (void)configureLegacyBackItem:(nullable UINavigationItem *)prevItem
       } else {
         attrs[NSFontAttributeName] = [UIFont boldSystemFontOfSize:[size floatValue]];
       }
-      [RNSScreenStackHeaderConfig setTitleAttibutes:attrs forButton:backBarButtonItem];
+      [RNSScreenStackHeaderConfig setTitleAttributes:attrs forButton:backBarButtonItem];
     }
 
     // Prevent unnecessary assignment of backBarButtonItem if it is not customized,

From 8009f8c62e5292871b1af8b16252fcfb0ae09766 Mon Sep 17 00:00:00 2001
From: Krzysztof Ligarski <krzysztof.ligarski@swmansion.com>
Date: Thu, 23 Oct 2025 15:43:57 +0200
Subject: [PATCH 8/8] fix reversed prop values in guide for lib authors

---
 guides/GUIDE_FOR_LIBRARY_AUTHORS.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/guides/GUIDE_FOR_LIBRARY_AUTHORS.md b/guides/GUIDE_FOR_LIBRARY_AUTHORS.md
index cf9d6a065b..919e14a6fa 100644
--- a/guides/GUIDE_FOR_LIBRARY_AUTHORS.md
+++ b/guides/GUIDE_FOR_LIBRARY_AUTHORS.md
@@ -582,11 +582,11 @@ If `backButtonUseModernImplementation` is set to `false`, this prop is used only
 
 ### `backButtonUseModernImplementation` (iOS only)
 
-Used for backward compatibility only. Setting this prop to `false` is recommended.
+Used for backward compatibility only. Setting this prop to `true` is recommended.
 
-Uses previous implementation of native back button configuration.
+Uses new implementation of native back button configuration.
 
-Default is `true`.
+Default is `false`.
 
 ### `headerLeftBarButtonItems` / `headerRightBarButtonsItems` (iOS only)