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 · 2026-07-17T14:02:12Z

    }
  }

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


setupHidePromise only gets nulled in the === promise success branch, but none of the destroy* methods or disconnectedCallback reset it, even though the guard comment says the disconnect case is handled. So if getScrollElement is still pending when the component disconnects (fast nav, tab switch) or scrollEffect switches away from hide, the stale promise still passes the identity check and we build a ScrollHideController + ResizeObserver and re-add the content partner classes, with nothing left to tear them down. I think setting this.setupHidePromise = null inside each destroy* method fixes it, since they run at the top of every checkCollapsible*/checkScrollEffect and in disconnectedCallback (matches the keyboardCtrlPromise handling and the pattern in components.md). Same thing applies to footer.tsx and tab-bar.tsx.

Great catch! I set this.setupHidePromise = null inside each destroy method in this commit 416cf50

ShaneK · 2026-07-17T14:55:15Z

-      const contentEl = pageEl ? findIonContent(pageEl) : null;
+    // condense/fade via the deprecated `collapse` prop are iOS-only.
+    // condense/fade via the new `scrollEffect` prop work in all themes.
+    const isModeRestricted = scrollEffect === undefined && getIonTheme(this) !== 'ios';


scroll-effect="condense" opens up for all themes here, but I think it ends up a visual no-op on md? The JS clones the large title and toggles header-collapse-condense, but only title.ios.scss and title.ionic.scss define :host(.title-large), so on md the large title renders at normal size and there's nothing to collapse. The condense e2e only checks the class/aria-hidden/role, so it passes either way. Was md large-title styling meant to be part of this, or is condense-on-md intentionally out of scope for now? A per-theme screenshot test would lock down whichever way you want it. Let me know if I'm missing something!

Thanks for catching this! Previously we didn't have a guard for the large title so the collapse was working. I added a check for the large title in this commit d976f01 and also added large title styling for the md theme in this commit d0ed544. I set the font size to match the large app bar for material design (https://m3.material.io/components/app-bars/specs) but will double check this with product.

ShaneK · 2026-07-17T14:56:47Z

+    const hasHide = (scrollEffect ?? collapse) === 'hide';
+    const hasFade = (scrollEffect ?? collapse) === 'fade';

    this.destroyCollapsibleFooter();


checkCollapsibleFooter runs from componentDidUpdate, and keyboardVisible is @State, so every keyboard show/hide re-renders and this destroyCollapsibleFooter() resets isHidden, strips footer-scroll-hidden, then rebuilds the controller + ResizeObserver. In practice a scroll-effect="hide" footer that you've scrolled away pops back into view the moment you focus an input, and it repeats on every keyboard toggle (losing the scroll hysteresis each time). tab-bar dodges this by driving setup from @Watch('scrollEffect') + componentDidLoad. Could header/footer do the same, or early-return when the resolved effect and content element haven't changed?

Great callout, I added an early return in 0ed301f

ShaneK · 2026-07-17T14:56:48Z

+    const { color, translucent, keyboardVisible, scrollEffect, expand } = this;
    const theme = getIonTheme(this);
    const shape = this.getShape();
    const shouldHide = keyboardVisible && this.el.getAttribute('slot') !== 'top';


setHidden sets aria-hidden imperatively for the scroll effect, but render() also owns it for the keyboard case (aria-hidden={shouldHide ? 'true' : null} just below). When a scroll-hidden tab-bar re-renders with shouldHide=false (keyboard closing), Stencil emits aria-hidden={null} and clears it, so the bar ends up inert + off-screen but no longer aria-hidden. inert covers the a11y hiding so it's not a hard break, but it's two writers on one attribute, and header/footer never render aria-hidden at all. Could tab-bar route the keyboard aria-hidden through the same imperative path so there's a single writer? Up to you.

Updated 3e74e1d

ShaneK · 2026-07-17T14:56:49Z

+ * won't activate it. Without this, the header renders as a
+ * normal visible header, adding unwanted height to the page.
+ */
+.header-md[collapse="condense"]:not(.header-collapse-condense) {


One thing I wanted to double check on the deprecated path: collapse isn't a reflected @Prop, and the Angular/Vue proxies bind it as a property, so under [collapse]="'condense'" there's no collapse attribute on the host and .header-md[collapse="condense"] won't match, which I think leaves the ghost header visible on md. header.common.scss already calls this out and targets both the attribute and the class for that reason. Was keying off the attribute a deliberate choice here, or should this match a class the way the :has() rule does?

Updated to use the class based approach in 9042365

ShaneK · 2026-07-17T14:56:52Z

-  private setupHideOnScroll() {
-    const theme = getIonTheme(this);
-    if (theme !== 'ionic' || !this.hideOnScroll || this.expand !== 'compact') {
+  private setupScrollEffect = async () => {


setupScrollEffect bails for any ancestor ion-footer, so <ion-footer><ion-tab-bar scroll-effect="hide"> where the footer has no scrollEffect (or fade) ends up hiding nothing, the tab-bar warns and returns and the footer isn't animating either. Letting the footer own the animation makes sense when the footer itself hides, but for a plain footer the prop just does nothing plus a console warning. Is that the intended final behavior? If so I think it's worth documenting on the prop rather than only warning at runtime, and if not, maybe only bail when the footer actually resolves to a hide effect.

I added a comment to document this b44fc68. If only ion-tab-bar is animated to hide, the footer visibly remains behind leaving an empty gap at the bottom of the page.

ShaneK · 2026-07-17T14:56:53Z

+ * same gesture.
+ *
+ * When the user reverses scroll direction, we save that position as
+ * an anchor. The bar only hides/shows after scrolling 60px past that


Nit: the module doc says the bar "only hides/shows after scrolling 60px past that anchor", but showing is immediate (requiredScrollDistance is 0 when scrolling up, and the wheel-up path shows with no distance check). Might be worth dropping the show side from that sentence so it only describes hiding. Up to you!

Fixed fa7d2d0

ShaneK · 2026-07-17T14:56:55Z

+// to fill the gap so no empty space is visible to the user.
+
+// Header gap compensation — only when content is NOT fullscreen.
+// When fullscreen=true, inner-scroll already fills the full viewport


Nit: this reads inverted to me. offset-top = 0 is the non-fullscreen case, not fullscreen. In fullscreen --offset-top is the header height. The gate itself is fine, just the reasoning in the comment. No worries if you'd rather leave it.

Fixed fa7d2d0

ShaneK · 2026-07-17T14:56:56Z

-  z-index: 0;
-}
-
 .header-collapse-condense ion-toolbar:last-of-type {


Nit: I think this is a leftover from the ios -> common move? .header-collapse-condense ion-toolbar:last-of-type { --border-width: 0px } now lives in header.common.scss too, which the ios bundle pulls in via header.native, so this copy looks redundant. Feel free to drop it if so.

This was intentional, in the ios theme specifically the common style is overwritten by the .header-ios ion-toolbar:last-of-type selector so we need to add it back here.

ShaneK · 2026-07-17T14:56:56Z


-    if (isScrollingDown !== wasScrollingDown) {
-      this.scrollDirectionChangeTop = this.lastScrollTop;
+  private destroyScrollEffect() {


Nit: the mechanism converged really nicely across the three, but the method names still differ a bit, tab-bar has setupScrollEffect/destroyScrollEffect where header/footer have setupScrollEffectHide/destroyCollapsible*. Might be worth aligning them (or a quick comment on why tab-bar's differ) so they read the same at a glance. Totally optional.

I added a comment around this but I kept them named differently because the tab bar only supports hide, whereas the header and footer have multiple scroll effects (collapse, fade, hide) fa7d2d0

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

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

34c991c

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

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!

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!

OS-susmitabhowmik Jul 17, 2026 • 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!

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!

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

OS-susmitabhowmik Jul 17, 2026 •

edited

Loading