Skip to content

fix(iOS): prevent back button icon from "jumping" during pop animation when display mode minimal is set #2800

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Mar 28, 2025
Merged

fix(iOS): prevent back button icon from "jumping" during pop animation when display mode minimal is set #2800

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d9beb18
Hide the back button title using display mode
kkafar Mar 24, 2025
b49dd22
chore: update docs
maciekstosio Mar 25, 2025
8fa3316
Update guides/GUIDE_FOR_LIBRARY_AUTHORS.md
maciekstosio Mar 26, 2025
752ca27
chore: add changes from comments
maciekstosio Mar 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion guides/GUIDE_FOR_LIBRARY_AUTHORS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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. 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). The `backTitleVisible` forces `backButtonDisplayMode: minimal` and omits other values. Read more [#2800](https://github.com/software-mansion/react-native-screens/pull/2800)

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
Expand Down
15 changes: 5 additions & 10 deletions ios/RNSScreenStackHeaderConfig.mm
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Copy link
Member Author

@kkafar kkafar Mar 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We don't need to wrap it inside ifdefs due to #2799 (min supported iOS version is 15.1 now


if (config.isBackTitleVisible) {
if ((config.backTitleFontFamily &&
Expand Down Expand Up @@ -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,
Expand Down
8 changes: 6 additions & 2 deletions native-stack/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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. 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). The `backTitleVisible` forces `backButtonDisplayMode: minimal` and omits other values. Read more [#2800](https://github.com/software-mansion/react-native-screens/pull/2800)

Possible options:
Copy link
Member Author

@kkafar kkafar Mar 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's apply my previous comment here also


- `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
Expand Down Expand Up @@ -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`

Expand Down
15 changes: 10 additions & 5 deletions src/native-stack/types.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -140,11 +140,12 @@ 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: `headerBackTitleStyle`, `disableBackButtonMenu`, `headerBackTitle` and `headerBackTitleVisible=false` is set.
*
* - `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'];
Expand Down Expand Up @@ -206,6 +207,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
Expand Down
16 changes: 11 additions & 5 deletions src/types.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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.
* To read more see [#2800](https://github.com/software-mansion/react-native-screens/pull/2800) and [#2800](https://github.com/software-mansion/react-native-screens/pull/2800).
Copy link
Member Author

@kkafar kkafar Mar 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think we should link these here. Previous link to apple docs should stay.

Copy link
Member Author

@kkafar kkafar Mar 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not useful when you trigger signature help.

*
* - `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;
Expand Down
Loading