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

kkafar · 2025-03-24T15:06:44Z

Description

See: react-navigation/react-navigation#12500
for issue description with videos.

We can use the backbuttondisplaymode to hide the backbuttontitle avoiding setting the title to nil
and therefore preventing the UIKit buggy back button icon animation.

@maciekstosio:
We agreed to leave backTitleVisible, so the API doesn't change in a minor version. The expected behavior is that backTitleVisible: false will work as "kill switch" and ignore other back button properties. When backTitleVisible: true other properties will work (including backButtonDisplayMode), but note that iOS omits backButtonDisplayMode when custom back button is provided (so when any of backTitleFontSize, backTitleFontFamily, headerBackButtonMenuEnabled, headerBackTitle is used).

Changes

☝️

Test code and steps to reproduce

You can use Test1084.

Simply set the headerBackButtonDisplayMode: 'minimal' on the second push screen.
Set headerLargeTitle: true on the first push screen.

How this has been tested

@maciekstosio:

I tested RNScreens properties by modifying props in react-navigation/packages/native-stack/src/views/useHeaderConfigProps.tsx.

I used Test1084, with the first screen having headerLargeTitle: true.

Tests:

When backTitleVisible: false:

backButtonDisplayMode is ignored
backTitleFontSize is ignored
backTitle is ignored (but it changes title in backButtonMenu)
disableBackButtonMenu is ignored

When backTitleVisible: true | undefined:

backButtonDisplayMode: minimal works
backButtonDisplayMode: generic works
backButtonDisplayMode: default works
backTitle works and overrides backButtonDisplayMode
headerBackTitleStyle.fontSize works and overrides backButtonDisplayMode
headerBackButtonMenuEnabled works and overrides backButtonDisplayMode

Checklist

Ensured that CI passes

kkafar

Notes for future us

kkafar · 2025-03-24T15:18:25Z

ios/RNSScreenStackHeaderConfig.mm

-#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;


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

kkafar

I really don't like the fact, that when backTitleVisible: false the disableBackButtonMenu is ignored.

However I don't see better solution right now. Any attempt to customise backBarButtonItem & hide the back title will introduce these much more jarring bugs.

@maciekstosio, can we update our types & later react-navigation types & documentation?

In our props we need to state which props introduce custom backBarButtonItem & under backButtonDisplayMode we need to state that it has no effect if backBarButtonItem is customised.

kkafar

Looks good, few last remarks. Thanks.
@maciekstosio

guides/GUIDE_FOR_LIBRARY_AUTHORS.md

kkafar · 2025-03-26T08:12:37Z

native-stack/README.md

+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:


Let's apply my previous comment here also

kkafar · 2025-03-26T08:14:55Z

src/types.tsx

-   * - "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).


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

This is not useful when you trigger signature help.

kkafar

Okay, I think we're good here. I'm gonna proceed & this can land in another beta.

kkafar · 2025-03-28T10:03:09Z

Let it be noted that CI fails for unrelated reasons (seems lik slow runner)

## Description This PR adds tests for #2809, #1589 and #2800. ## Changes The main assumption is to test all permutation of headerBackButtonMenuEnabled, headerBackButtonDisplayMode and content of button (default - taken from previous screen headerTitle, custom from headerBackTitle and styled when there are styles applied). I hope this will help us tracking regression as this part of the code is a bit confusing and caused us problem in the past. Additionally there are added "custom" scenarios that test default default behavior with default text and custom text (if the back button changes it's appearance depending on available space and [headerBackButtonDisplayMode](https://developer.apple.com/documentation/uikit/uinavigationitem/backbuttondisplaymode-swift.property) specification). The some of the last cases are set to failing, and this is known disparity reported in #2809, we plan to fix it soon after, but wonted to make sure we don't cause a regression. **Remark:** I did it in a way that after each test we're returning to the screen with all test cases for 2809, this is due to the fact that scrolling through list of all Test* takes a lot and reloading RN after each test would cause huge overhead. The downside of it is that if any of the test fails if will cascade fail all other. ## Test code and steps to reproduce You can run test with: ``` detox build --configuration ios.sim.debug detox test --configuration ios.sim.debug e2e/issuesTests/Test2809.e2e.ts -l debug ```` ## Checklist - [ ] Ensured that CI passes

…#2867) ## Description / Changes This is continuation of #2860 that proposes small refactor around back button logic. This area is very confusing and in my opinion this is due to flag `shouldUseCustomBackBarButtonItem` that breaks the flow of other if's and causes other props to not work. Not we contained this flag in `if (visible)` which currently is the only case when backButtonItem might be used after the changes from #2800. ## Test code and steps to reproduce see `FabricExample/e2e/issuesTests/Test2809.e2e.ts` and `apps/src/tests/Test2809/index.tsx` ## Checklist - [ ] Ensured that CI passes --------- Co-authored-by: Kacper Kafara <[email protected]>

kkafar mentioned this pull request Mar 24, 2025

fix: jumping back button react-navigation/react-navigation#12500

Merged

Hide the back button title using display mode

d9beb18

kkafar force-pushed the @kkafar/playaround-with-headerconfig-3 branch from f67b64c to d9beb18 Compare March 24, 2025 15:17

kkafar commented Mar 24, 2025

View reviewed changes

kkafar commented Mar 25, 2025

View reviewed changes

chore: update docs

b49dd22

kkafar commented Mar 26, 2025

View reviewed changes

maciekstosio added 2 commits March 26, 2025 12:00

Update guides/GUIDE_FOR_LIBRARY_AUTHORS.md

8fa3316

chore: add changes from comments

752ca27

kkafar commented Mar 28, 2025

View reviewed changes

kkafar merged commit cc73b18 into main Mar 28, 2025
7 of 8 checks passed

kkafar deleted the @kkafar/playaround-with-headerconfig-3 branch March 28, 2025 10:05

This was referenced Apr 3, 2025

[IOS] headerLargeTitle: true with headerBackTitleVisible: false makes back button animation jerky #2548

Open

headerLargeTitle: true with headerBackTitleVisible: false makes back button animation jerky react-navigation/react-navigation#11946

Closed

maciekstosio mentioned this pull request Apr 9, 2025

chore(iOS, Fabric): add tests for header interactions #2848

Merged

1 task

This was referenced Apr 11, 2025

chore(iOS): refactor back button logic #2861

Closed

refactor(iOS): limit scope of shouldUseCustomBackBarButtonItem flag #2867

Merged

kligarski mentioned this pull request Oct 16, 2025

feat(iOS, Stack): update back button configuration logic to handle iOS 26 and fix other problems #3303

Open

8 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

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

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

Uh oh!

kkafar commented Mar 24, 2025 •

edited

Loading

Uh oh!

kkafar left a comment

Uh oh!

kkafar Mar 24, 2025

Uh oh!

kkafar left a comment

Uh oh!

kkafar left a comment •

edited

Loading

Uh oh!

Uh oh!

kkafar Mar 26, 2025

Uh oh!

kkafar Mar 26, 2025

Uh oh!

kkafar Mar 26, 2025

Uh oh!

kkafar left a comment

Uh oh!

kkafar commented Mar 28, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		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:

Uh oh!

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

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

Uh oh!

Conversation

kkafar commented Mar 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Changes

Test code and steps to reproduce

How this has been tested

Checklist

Uh oh!

kkafar left a comment

Choose a reason for hiding this comment

Uh oh!

kkafar Mar 24, 2025

Choose a reason for hiding this comment

Uh oh!

kkafar left a comment

Choose a reason for hiding this comment

Uh oh!

kkafar left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

kkafar Mar 26, 2025

Choose a reason for hiding this comment

Uh oh!

kkafar Mar 26, 2025

Choose a reason for hiding this comment

Uh oh!

kkafar Mar 26, 2025

Choose a reason for hiding this comment

Uh oh!

kkafar left a comment

Choose a reason for hiding this comment

Uh oh!

kkafar commented Mar 28, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

kkafar commented Mar 24, 2025 •

edited

Loading

kkafar left a comment •

edited

Loading