feat(header, footer, tab-bar): add scrollEffect prop by OS-susmitabhowmik · Pull Request #31263 · ionic-team/ionic-framework

OS-susmitabhowmik · 2026-07-10T19:34:12Z

Issue number: resolves internal

What is the current behavior?

ion-header and ion-footer have a collapse prop for scroll-driven effects (condense, fade), but it only works on the iOS theme.
ion-tab-bar has an unreleased hideOnScroll boolean prop that only works on the Ionic theme with expand="compact".

What is the new behavior?

Adds a new scrollEffect string enum prop to ion-header, ion-footer, and ion-tab-bar.
scrollEffect="hide" slides the bar out of view when scrolling down and back in when scrolling up.
scrollEffect="condense" and scrollEffect="fade" on ion-header/ion-footer replace the existing collapse values and work across all themes.
Deprecates the collapse prop on ion-header and ion-footer with a console warning directing developers to use scrollEffect.
Removes the unreleased hideOnScroll prop from ion-tab-bar.
When ion-tab-bar is nested inside ion-footer, the footer owns the hide animation to prevent double-animation

Does this introduce a breaking change?

Yes
No

Other information

Relevant Test Pages:

Header

Footer

Tab Bar

…oll animation

…rrect theme class usage

…orce footer priority

…llEffect in all modes

…d controller

vercel · 2026-07-10T19:34:18Z

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

Project	Deployment	Actions	Updated (UTC)
ionic-framework	Ready	Preview, Comment	Jul 17, 2026 11:50pm

…rendering

ShaneK

Hey, great work on this! I highlighted a few issues I found, some of them aren't as important as others, but still

ShaneK

Hey! Thanks for fixing up those issues! I found some more things that were a bit concerning with this change, let me know if I'm off the mark on anything here!

ShaneK

Thanks for grinding through all of this, most of the last round holds up and I verified it. Found a few more edges though, including one where the main header disappears with no large title (reproduced it inline). Nothing structural, mostly tightening up the cases we keep uncovering. Let me know if I'm off base on any of these!

ShaneK · 2026-07-20T14:07:37Z

+     * collapse into the main header toolbar.
+     */
+    const hasLargeTitle = this.el.querySelector('ion-title[size="large"]') !== null;
+    if (!hasLargeTitle) {


I pulled the branch and this one renders the page with no visible header on both md and ios. When a condense header has a plain (non-large) title, the header-collapse-condense class still gets applied in render(), but setupCondenseHeader bails on this large-title guard before it reaches the code that adds header-collapse-main to the primary header. So the :has() ghost-hide rule in header.common.scss pins the main header at opacity: 0 and nothing ever releases it.

Repro is /header/test/scroll-effect-condense-no-large-title: the main header computes to opacity: 0 and never gets header-collapse-main. The new e2e only screenshots the condense header, so it doesn't catch the main one vanishing.

I think we either gate the header-collapse-condense class on a large title too, or keep assigning header-collapse-main when we bail here. Worth a test that asserts the main header stays visible in the no-large-title case.

ShaneK · 2026-07-20T14:07:50Z

+   * `"condense"` collapses the large title into the main toolbar on scroll.
+   * `"fade"` fades the toolbar background on scroll.
+   */
+  @Prop() scrollEffect?: HeaderScrollEffect;


Since scrollEffect isn't reflected, this breaks down under framework property binding. I set the prop as a property (the way the Angular/Vue/React proxies bind it) and confirmed no scroll-effect attribute lands on the host, so el.matches('[scroll-effect="condense"]') is false and the class only appears after render.

That trips up the fade setup's querySelector('...ion-header[scroll-effect="condense"]') on line 161, which has no class fallback, so a fade header paired with a property-bound condense sibling loses the coordination and fades in immediately. The :has() flash guard has the same gap in the pre-hydration window.

Adding reflect: true here would make both selectors robust and match the comment in header.common.scss that already assumes it's reflected. Flagging in case reflection was intended and just got missed.

ShaneK · 2026-07-20T14:07:59Z

-      React.PropsWithoutRef<StencilReactExternalProps<PropType, ElementType>>
-    >
-  );
+  return React.forwardRef(forwardRef);


This looks unrelated to the scroll effect work, and it reverts the explicit forwardRef cast (plus the comment explaining it) that's still on next. Feels like a bad merge? It re-widens the type the cast was guarding. Could we drop this hunk unless it's intentional?

ShaneK · 2026-07-20T14:08:09Z

+      this.el.setAttribute('aria-hidden', 'true');
+    } else {
+      this.el.removeAttribute('inert');
+      this.el.removeAttribute('aria-hidden');


The commit says this unifies aria-hidden under one imperative writer, but there are still two paths that disagree. The keyboard callback ORs the keyboard and scroll conditions, while setHidden(false) here clears aria-hidden and inert unconditionally.

I reproduced it: with the keyboard open on a bottom tab bar (aria-hidden correctly true), scrolling down then back to the top fires setHidden(false), which strips both aria-hidden and inert while the keyboard is still open, so the off-screen tab bar gets exposed to AT again. Could setHidden OR in the keyboard state too, or route both writers through one function?

ShaneK · 2026-07-20T14:08:22Z

+    const hasFade = effect === 'fade';

    this.destroyCollapsibleHeader();
+    this.activeEffect = effect;


We set this.activeEffect = effect here before the setup actually runs, and the setup below is gated on contentEl (condense/fade have their own early returns too). If content mounts late (behind an *ngIf/v-if), the effect gets marked active with nothing wired up, and the effect === this.activeEffect guard above then short-circuits every later componentDidUpdate, so it never recovers.

I reproduced this with deferred content: the header never picks up content-header-hide-scroll-partner even after the content appears and the header re-renders, while the same setup with content present up front works fine. Same deal in footer.tsx. I think setting activeEffect only after setup succeeds would fix it.

ShaneK · 2026-07-20T14:08:31Z

+      await content.evaluate((el: HTMLIonContentElement) => el.scrollToBottom(0));
+      await page.locator('ion-header.header-scroll-hidden').waitFor();
+
+      await expect(header).toHaveClass(/header-scroll-hidden/);


The hide effect is the headline of the PR but it's the one effect with no visual or computed-style coverage. These assert the class and inert but never that the bar actually moves. The condense tests have screenshots and the fade ones check --opacity-scale, so hide is the odd one out.

If a theme bundle ever dropped the transform rule, the bar would sit on screen but inert over the gap-compensated content, and every test here would still pass. Could we add one toHaveScreenshot() or a getComputedStyle(...).transform check in the hidden state? Applies to the footer and tab-bar hide specs too.

ShaneK · 2026-07-20T14:08:44Z

    }
  }

+  private setupScrollEffectHide = async (contentEl: HTMLElement) => {


Nit / future maintenance: the controller cleanly owns the scroll math, but the wiring around it (the promise-identity guard, the ResizeObserver, the --internal-*-hide-height read/write, the content partner-class toggling, and the teardown) is copy-pasted almost verbatim across header, footer, and tab-bar. A fix to the hide behavior has to land in three places now.

Since all three already share the controller, could we push that wiring into it (or a small partner helper that takes the css var + class names) so it lives once? Fine to leave for a follow-up though.

ShaneK · 2026-07-20T14:08:55Z

+  // Named differently from header/footer's destroyCollapsible* because
+  // tab-bar only supports "hide", while header/footer handle multiple
+  // effects (hide, condense, fade) through one teardown method.


Suggested change

// Named differently from header/footer's destroyCollapsible* because

// tab-bar only supports "hide", while header/footer handle multiple

// effects (hide, condense, fade) through one teardown method.

Nit: this reads more like PR context than something the code needs. The method name already says what it does, and it points at destroyCollapsible* in the other files which'll go stale if those get renamed. Up to you though!

OS-susmitabhowmik added 11 commits July 7, 2026 15:43

feat(header,footer,tab-bar): add scrollEffect=hide cross-platform scr…

584acd2

…oll animation

fix(header,footer,tab-bar): restore accidentally removed props and co…

02cdca8

…rrect theme class usage

refactor(header,footer,tab-bar): improve scroll effect code readability

f14e78e

fix(header,footer,tab-bar): remove theme restrictions

8fdd497

fix(tab-bar): fix compact scroll-effect-hide animating diagonally

42e044d

fix(header): scope banner role toggling to iOS mode only

07a60ca

test(header,footer,tab-bar): add scroll-effect-hide e2e tests and enf…

4a25aa1

…orce footer priority

fix(tab-bar): fix scroll-effect-hide tests

9e1932b

fix(header,footer): restrict collapse prop effects to ios, allow scro…

1aa051a

…llEffect in all modes

test(header,footer): fix tests

9ad2c05

refactor(header,footer,tab-bar): extract scroll-hide logic into share…

11ea3b3

…d controller

github-actions Bot added package: core @ionic/core package package: angular @ionic/angular package package: vue @ionic/vue package package: react @ionic/react package labels Jul 10, 2026

fix(tab-bar): add aria-hidden for hiding on scroll

4f407ca

vercel Bot deployed to Preview July 13, 2026 16:15 View deployment

chore(): fix stylelint errors

8f8fa2d

vercel Bot deployed to Preview July 13, 2026 16:28 View deployment

chore(): fix linter errors

cbab4fd

vercel Bot deployed to Preview July 13, 2026 16:44 View deployment

OS-susmitabhowmik marked this pull request as ready for review July 13, 2026 17:01

OS-susmitabhowmik requested a review from a team as a code owner July 13, 2026 17:01

OS-susmitabhowmik requested a review from ShaneK July 13, 2026 17:01

refactor(header): clean up condense header lookup and collapse class …

6dbad44

…rendering

github-actions Bot removed the package: react @ionic/react package label Jul 13, 2026

vercel Bot deployed to Preview July 13, 2026 18:47 View deployment

ShaneK requested changes Jul 14, 2026

View reviewed changes

feat(header,footer): add fade/condense support for all themes

d405790

vercel Bot deployed to Preview July 16, 2026 01:27 View deployment

chore(): lint

3b045eb

vercel Bot deployed to Preview July 16, 2026 01:37 View deployment

chore(): use background color instead of image in fade test pages

129ee39

vercel Bot deployed to Preview July 16, 2026 18:19 View deployment

refactor(tab-bar): use imperative hide state to match header and footer

ba3d26e

OS-susmitabhowmik requested a review from ShaneK July 16, 2026 18:49

vercel Bot deployed to Preview July 16, 2026 18:49 View deployment

ShaneK requested changes Jul 17, 2026

View reviewed changes

OS-susmitabhowmik added 7 commits July 17, 2026 12:56

fix(header,footer,tab-bar): invalidate setupHidePromise on teardown

416cf50

feat(title): add large title styles for md theme

d0ed544

fix(header,footer): skip scroll effect rebuild when effect unchanged

0ed301f

fix(tab-bar): unify aria-hidden under a single imperative writer

3e74e1d

fix(header): hide deprecated condense header on all non-iOS themes

9042365

docs(tab-bar): add empty footer reasoning to scrollEffect note

b44fc68

chore(): improve comments across scroll effect components

fa7d2d0

vercel Bot deployed to Preview July 17, 2026 21:11 View deployment

Ionitron and others added 2 commits July 17, 2026 21:21

chore(): add updated snapshots

6da02c3

chore(): fix build and lint

e3e0289

vercel Bot deployed to Preview July 17, 2026 21:32 View deployment

chore(): add updated snapshots

6ac42b0

vercel Bot deployed to Preview July 17, 2026 22:02 View deployment

chore(): add updated snapshots

5233ade

vercel Bot deployed to Preview July 17, 2026 22:30 View deployment

fix(header): guard condense scroll effect to require large title

d976f01

vercel Bot deployed to Preview July 17, 2026 23:31 View deployment

chore(): add updated snapshots

cc2a940

vercel Bot deployed to Preview July 17, 2026 23:50 View deployment

OS-susmitabhowmik requested a review from ShaneK July 18, 2026 00:35

ShaneK requested changes Jul 20, 2026

View reviewed changes

	// Named differently from header/footer's destroyCollapsible* because
	// tab-bar only supports "hide", while header/footer handle multiple
	// effects (hide, condense, fade) through one teardown method.

Uh oh!

Conversation

OS-susmitabhowmik commented Jul 10, 2026 • 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

Relevant Test Pages:

Header

Footer

Tab Bar

Uh oh!

vercel Bot commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ShaneK left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ShaneK left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ShaneK 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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

OS-susmitabhowmik commented Jul 10, 2026 •

edited

Loading

vercel Bot commented Jul 10, 2026 •

edited

Loading