diff --git a/guides/GUIDE_FOR_LIBRARY_AUTHORS.md b/guides/GUIDE_FOR_LIBRARY_AUTHORS.md index 5808e4f553..194c480b6a 100644 --- a/guides/GUIDE_FOR_LIBRARY_AUTHORS.md +++ b/guides/GUIDE_FOR_LIBRARY_AUTHORS.md @@ -502,6 +502,8 @@ Allows for customizing font size to be used for back button title on iOS. 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. + ### `blurEffect` (iOS only) Blur effect to be applied to the header. Works with `backgroundColor`'s alpha < 1. @@ -520,7 +522,9 @@ Boolean indicating whether to show the menu on longPress of iOS >= 14 back butto ### `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). Possible options: +Enum value indicating display mode of back button. It is used only when none of: `backTitleFontFamily`, `backTitleFontSize`, `disableBackButtonMenu`, `backTitle` 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). + +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 diff --git a/ios/RNSScreenStackHeaderConfig.mm b/ios/RNSScreenStackHeaderConfig.mm index 0c5b76b68f..9046fc5009 100644 --- a/ios/RNSScreenStackHeaderConfig.mm +++ b/ios/RNSScreenStackHeaderConfig.mm @@ -631,12 +631,9 @@ + (void)updateViewController:(UIViewController *)vc auto shouldUseCustomBackBarButtonItem = !isBackTitleBlank || config.disableBackButtonMenu; -#if defined(__IPHONE_OS_VERSION_MAX_ALLOWED) && defined(__IPHONE_14_0) && \ - __IPHONE_OS_VERSION_MAX_ALLOWED >= __IPHONE_14_0 - if (@available(iOS 14.0, *)) { - prevItem.backButtonDisplayMode = config.backButtonDisplayMode; - } -#endif + // 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) { if ((config.backTitleFontFamily && @@ -666,11 +663,9 @@ + (void)updateViewController:(UIViewController *)vc // back button title should be not visible next to back button, // but it should still appear in back menu (if one is enabled) - // When backBarButtonItem's title is null, back menu will use value - // of backButtonTitle - [backBarButtonItem setTitle:nil]; - shouldUseCustomBackBarButtonItem = YES; prevItem.backButtonTitle = resolvedBackTitle; + prevItem.backButtonDisplayMode = UINavigationItemBackButtonDisplayModeMinimal; + shouldUseCustomBackBarButtonItem = NO; } // Prevent unnecessary assignment of backBarButtonItem if it is not customized, diff --git a/native-stack/README.md b/native-stack/README.md index f87fa5dfe9..7e933661ec 100644 --- a/native-stack/README.md +++ b/native-stack/README.md @@ -82,7 +82,9 @@ Boolean indicating whether to show the menu on longPress of iOS >= 14 back butto #### `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). Possible options: +Enum value indicating display mode of back button. It is used only when none of: `backTitleFontFamily`, `backTitleFontSize`, `disableBackButtonMenu`, `backTitle` 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). + +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 @@ -128,7 +130,9 @@ Style object for header back title. Supported properties: #### `headerBackTitleVisible` (iOS only) -Whether the back button title should be visible or not. Defaults to `true`. +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. #### `headerCenter` diff --git a/src/native-stack/types.tsx b/src/native-stack/types.tsx index 1f04534ee6..d7fb0487e7 100644 --- a/src/native-stack/types.tsx +++ b/src/native-stack/types.tsx @@ -140,11 +140,13 @@ export type NativeStackNavigationOptions = { */ 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 + * How the back button behaves. It is used only when none of: `backTitleFontFamily`, `backTitleFontSize`, `disableBackButtonMenu`, `backTitle` and `backTitleVisible=false` is set. + * 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 + * - `minimal` – show just an icon + * * @platform ios */ backButtonDisplayMode?: ScreenStackHeaderConfigProps['backButtonDisplayMode']; @@ -206,6 +208,10 @@ export type NativeStackNavigationOptions = { }; /** * 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`, + * `headerBackTitleStyle`, `disableBackButtonMenu`. For `headerBackTitle` it works only in back button menu. + * * Only supported on iOS. * * @platform ios diff --git a/src/types.tsx b/src/types.tsx index 0f4dddaba3..ceafa8ea4c 100644 --- a/src/types.tsx +++ b/src/types.tsx @@ -544,6 +544,10 @@ 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. + * * @platform ios */ backTitleVisible?: boolean; @@ -570,11 +574,13 @@ export interface ScreenStackHeaderConfigProps extends ViewProps { */ 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 + * How the back button behaves. It is used only when none of: `backTitleFontFamily`, `backTitleFontSize`, `disableBackButtonMenu`, `backTitle` and `backTitleVisible=false` is set. + * 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 + * - `minimal` – show just an icon + * * @platform ios */ backButtonDisplayMode?: BackButtonDisplayMode;