How the header collapses
The rules that keep the header glued to content — and jump-free.
Scrolling down collapses the header in sync with the content. Scrolling up (the default) keeps the header collapsed until the content top reaches it again, then expands it in sync — so the header never detaches from content and never leaves a gap.
With revealHeaderOnScroll, any upward delta expands the header immediately (Twitter-style). When snap is enabled, it animates whichever transition keeps the content gapless.
⚠ Translucent headers need a solid background
The header needs a solid headerBackgroundColor because per-tab scroll memory means deep-scrolled content can legitimately sit underneath an expanded header. That trade is exactly what makes tab switches jump-free.
⚠ Animate header content in place
A custom header animation should fade or scale in place. Don’t translate header content upward as it collapses, or it rides past minHeaderHeight into the safe-area / status-bar region and overlaps it. Content that must stay visible while the header collapses (a progress bar, a search field) belongs in the tab bar via renderTabBar — the header scrolls away, the tab bar stays pinned.