fix(header): prevent flickering during iOS page transitions #30705

thetaPC · 2025-10-03T17:39:26Z

Issue number: resolves #25326

What is the current behavior?

The header flickers upon page transition when on iOS mode and using a condensed header:

Entering Page Two (P1 → P2):
When navigating to Page Two, which has a collapsing header (intended to be hidden until scroll), the header briefly flashes into view. This happens because the header is initially rendered with full opacity: 1 before the component's logic can apply opacity: 0 to hide it, causing a visible flicker.

Navigating Back (P2 → P1):
When navigating back, Page One's header briefly bleeds through the top of Page Two. Although Page Two is on top (z−index: 100), its collapsing header is set to opacity: 0. This transparency allows Page One header (z−index: 99) to become visible underneath, as the transparent area cannot block the content below it.

The header flickers upon page transition when on iOS mode and using a fade header:

Entering Page Two (P1 → P2):
When navigating to Page Two, which has a fade header (should not have a background on load), the header background briefly flashes into view. This happens because the header is initially rendered with full opacity: 1 before the component's logic can apply opacity: 0 to hide it, causing a visible flicker.

What is the new behavior?

Added a transition-specific class that is applied to the condensed ion-header element to override its default transparency.

This guarantees the header to act as an opaque block during the page transition, eliminating visual flickering caused by early opacity: 0 or the header underneath bleeding through.

Added a transition-specific class that is applied to the fade ion-header element to override its default opaque background.

This guarantees the header to act as a transparent block during the page transition, eliminating visual flickering caused by default opacity: 1.

Does this introduce a breaking change?

Yes
No

Other information

Dev build: 8.7.6-dev.11759524961.1cff6814

vercel · 2025-10-03T17:39:32Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
ionic-framework	Ready	Preview	Comment	Oct 6, 2025 4:25pm

thetaPC · 2025-10-03T17:40:09Z

core/src/components/header/header.ios.scss

+ * Large title toolbar should just use the content background
+ * since it needs to blend in with the header above it.
+ */
+.header-collapse-condense ion-toolbar,


This is the large title that is tied to the inactive header.

thetaPC · 2025-10-03T19:07:05Z

core/src/components/header/header.ios.scss

+.header-collapse-condense ion-toolbar,
+/**
+ * Override styles applied during the page transition to prevent
+ * header flickering.
+ */
+.header-collapse-condense-inactive.header-transitioning:not(.header-collapse-condense) ion-toolbar {
+  --background: var(--ion-background-color, #fff);
+}


I grouped these together so they will always be the same background color since they are related to the condensed header.

thetaPC · 2025-10-03T19:07:55Z

core/src/utils/transition/index.ts

-        (result) => {
-          if (result.animation) {
-            result.animation.destroy();
+      const transitioningInactiveHeader = getIosIonHeader(opts);


I'm grabbing the header here so we don't have to do query it twice within beforeTransition and in the finally.

thetaPC · 2025-10-03T19:08:18Z

core/src/utils/transition/index.ts

+        )
+        .finally(() => {
+          // Ensure that the header is restored to its original state.
+          setHeaderTransitionClass(transitioningInactiveHeader, false);


Removed the class here since it should be removed regardless of the success of runTransition.

thetaPC · 2025-10-03T19:08:51Z

core/src/utils/transition/index.ts

+    return;
+  }
+
+  const transitionClass = 'header-transitioning';


I'm open to a different name. I'm not too happy with it but not sure what else to call it to be specific.

I think this makes sense. It's added to the header during the transition.

thetaPC · 2025-10-03T19:09:40Z

core/src/utils/transition/index.ts

+  if (mode !== 'ios') {
+    return null;
+  }


I didn't see the benefit of querying out the header if the mode is md. However, we would have to update this in next to use theme instead of mode.

I am fine with this but yeah we will need to update it eventually so that we are using the theme (or a config option for it if one is added).

Is there a specific ticket I can associate it to?

No I don't think we've created tickets that far. We will just have to query for where mode is checked.

thetaPC · 2025-10-03T21:04:00Z

core/src/utils/transition/index.ts

+        )
+        .finally(() => {
+          // Ensure that the header is restored to its original state.
+          setHeaderTransitionClass(transitioningInactiveHeader, false);


Removed class at the end so the header can go back to its default, preventing any potential regressions.

brandyscarney

Great work!

brandyscarney · 2025-10-09T19:44:35Z

core/src/utils/transition/index.ts

+  if (mode !== 'ios') {
+    return null;
+  }


I am fine with this but yeah we will need to update it eventually so that we are using the theme (or a config option for it if one is added).

brandyscarney · 2025-10-09T19:45:48Z

core/src/utils/transition/index.ts

+    return;
+  }
+
+  const transitionClass = 'header-transitioning';


I think this makes sense. It's added to the header during the transition.

ShaneK · 2025-10-14T13:00:35Z

Great work, Maria! Looks awesome!

fix(header): prevent flickering upon page transition on iOS

1a976aa

github-actions bot added the package: core @ionic/core package label Oct 3, 2025

thetaPC commented Oct 3, 2025

View reviewed changes

thetaPC changed the title ~~fix(header): prevent flickering upon page transition on iOS~~ fix(header): prevent flickering during iOS page transitions Oct 3, 2025

thetaPC marked this pull request as ready for review October 3, 2025 20:13

thetaPC requested a review from a team as a code owner October 3, 2025 20:13

thetaPC requested a review from ShaneK October 3, 2025 20:13

fix(header): prevent flickering when using fade

cff6814

vercel bot deployed to Preview October 3, 2025 20:51 View deployment

thetaPC commented Oct 3, 2025

View reviewed changes

docs(header): update comment

b99e370

vercel bot deployed to Preview October 6, 2025 16:25 View deployment

brandyscarney reviewed Oct 9, 2025

View reviewed changes

brandyscarney approved these changes Oct 9, 2025

View reviewed changes

ShaneK approved these changes Oct 14, 2025

View reviewed changes

thetaPC added this pull request to the merge queue Oct 14, 2025

Merged via the queue into main with commit 820fa28 Oct 14, 2025
51 checks passed

thetaPC deleted the FW-6765 branch October 14, 2025 17:59

thetaPC mentioned this pull request Oct 14, 2025

bug: ios transition does not account for fade header #25326

Closed

7 tasks

fix(header): prevent flickering during iOS page transitions #30705

fix(header): prevent flickering during iOS page transitions #30705

Conversation

thetaPC commented Oct 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What is the current behavior?

What is the new behavior?

Does this introduce a breaking change?

Other information

Uh oh!

vercel bot commented Oct 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

brandyscarney left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ShaneK commented Oct 14, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

thetaPC commented Oct 3, 2025 •

edited

Loading

vercel bot commented Oct 3, 2025 •

edited

Loading