Scroll-Driven Effects & Sticky Headers

position: sticky and IntersectionObserver are complementary, not competing. Let CSS position: sticky do the actual pinning — the compositor thread handles it without any JavaScript involvement — and use the observer purely to detect when the sticky element has become pinned, so you can add a shadow, compact the layout, or swap a logo variant at that exact moment:

#site-header {
  position: sticky;
  top: 0;
  transition: box-shadow 0.15s ease;
}
#site-header.is-pinned {
  box-shadow: 0 2px 8px rgb(0 0 0 / 0.12);
}

// Detect the moment `position: sticky` engages, without polling getBoundingClientRect()
const stickySentinel = document.createElement('div');
stickySentinel.style.cssText = 'position:absolute;top:0;height:1px;width:1px;';
header.parentElement!.insertBefore(stickySentinel, header);

new IntersectionObserver(([entry]) => {
  header.classList.toggle('is-pinned', !entry.isIntersecting);
}, { threshold: 0 }).observe(stickySentinel);

Edge Cases & Gotchas

Sticky headers inside scrollable containers, not the document. If the header lives inside a scrollable <div> rather than the page body, the observer's root must be set to that container explicitly — the default root: null only tracks the top-level document viewport, and the sentinel will never appear to leave a container it is not actually scrolling within.

Rapid scroll produces coalesced crossings. On a fast trackpad fling, the sentinel may cross the boundary and come back before the browser delivers a callback, or several crossings may coalesce into one notification. Always read the current isIntersecting value from the delivered entry rather than assuming exactly one callback per physical crossing.

Reveal animations firing on page load for above-the-fold content. Because observe() always delivers one synchronous-feeling notification immediately, elements already visible at load will report isIntersecting: true right away and play their entrance animation on load rather than on scroll. This is usually desirable, but if you want above-the-fold elements to render already-visible with no animation, check entry.boundingClientRect.top against 0 before the first paint and mark those elements as pre-revealed synchronously.

Scroll-spy with sections shorter than the rootMargin band. If a section's height is smaller than the centered band created by a -40% top/bottom rootMargin, the section may never fully enter the band and will be skipped by nav highlighting. Fall back to intersectionRatio comparison across all currently intersecting entries rather than assuming exactly one section is ever "the" active one.

Layout thrash from measuring header height on every pin/unpin. If your layout reserves space for a header using a spacer element sized to the header's offsetHeight, do not re-measure that height inside the observer callback — cache it once on load and only re-measure on a debounced ResizeObserver callback for the header itself, since IntersectionObserver alone does not report size changes.

iOS Safari address bar transitions. The dynamic show/hide of the mobile browser chrome changes the visual viewport height mid-scroll, which can produce a spurious sentinel crossing unrelated to actual page scroll. Debounce class toggles by a single animation frame so a transient chrome-driven flicker does not visibly double-toggle the pinned state.

Framework Integration Patterns

React — pinned-header hook

import { useEffect, useRef, useState } from 'react';

function useHeaderPin(rootMargin = '-1px 0px 0px 0px'): [React.RefObject<HTMLDivElement>, boolean] {
  const sentinelRef = useRef<HTMLDivElement>(null);
  const [isPinned, setPinned] = useState(false);

  useEffect(() => {
    if (!sentinelRef.current) return;
    const observer = new IntersectionObserver(([entry]) => {
      setPinned(!entry.isIntersecting);
    }, { rootMargin });
    observer.observe(sentinelRef.current);
    return () => observer.disconnect();
  }, [rootMargin]);

  return [sentinelRef, isPinned];
}

Vue 3 — reveal-on-scroll directive

import { onMounted, onUnmounted, ref } from 'vue';

export function useRevealOnScroll(threshold = 0.2) {
  const el = ref<HTMLElement | null>(null);
  const revealed = ref(false);
  let observer: IntersectionObserver | null = null;

  onMounted(() => {
    if (!el.value) return;
    const reduceMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
    observer = new IntersectionObserver(([entry]) => {
      if (!entry.isIntersecting) return;
      revealed.value = true;
      observer?.unobserve(entry.target);
      if (reduceMotion) el.value?.classList.add('is-visible');
    }, { threshold });
    observer.observe(el.value);
  });

  onUnmounted(() => observer?.disconnect());
  return { el, revealed };
}

Angular — sticky header directive

import { Directive, ElementRef, HostBinding, OnDestroy, OnInit } from '@angular/core';

@Directive({ selector: '[appStickyHeader]', standalone: true })
export class StickyHeaderDirective implements OnInit, OnDestroy {
  @HostBinding('class.is-pinned') isPinned = false;
  private observer!: IntersectionObserver;
  private sentinel!: HTMLDivElement;

  constructor(private el: ElementRef<HTMLElement>) {}

  ngOnInit(): void {
    this.sentinel = document.createElement('div');
    this.sentinel.style.cssText = 'height:0;';
    this.el.nativeElement.parentElement?.insertBefore(this.sentinel, this.el.nativeElement);

    this.observer = new IntersectionObserver(
      ([entry]) => { this.isPinned = !entry.isIntersecting; },
      { rootMargin: '-1px 0px 0px 0px' }
    );
    this.observer.observe(this.sentinel);
  }

  ngOnDestroy(): void {
    this.observer.disconnect();
    this.sentinel.remove();
  }
}

Debugging Checklist

Header never pins:

• Confirm the sentinel actually sits before the header in DOM order and has height: 0 rather than being accidentally hidden with display: none (which reports no intersection changes at all).
• Check that no ancestor has overflow: hidden clipping the sentinel out of the layout entirely.
• If the header lives in a scrollable panel, verify root is set to that panel, not left as the default document viewport.

Nav highlight jumps to the wrong section:

• Log every entry in the callback, not just the first — multiple sections are frequently intersecting simultaneously near a centered rootMargin band. Resolve ties by comparing intersectionRatio or boundingClientRect.top distance from center.
• Verify rootMargin percentages resolve against the viewport as expected; a band that is too wide (e.g. -10%) will report several sections as active at once.

Reveal animation replays on scroll-up:

• Confirm unobserve() is called immediately after the first isIntersecting: true entry. Without it, scrolling the element back into view retriggers the animation class every time.

Reproduction script:

// Paste in DevTools console to watch sentinel crossings live
const sentinel = document.querySelector('#header-sentinel');
new IntersectionObserver((entries) => {
  entries.forEach((e) => console.log('isIntersecting:', e.isIntersecting, 'top:', e.boundingClientRect.top.toFixed(1)));
}, { rootMargin: '-1px 0px 0px 0px' }).observe(sentinel);

For deeper timing analysis of how these callbacks line up with paint, see syncing observer callbacks with requestAnimationFrame; for the underlying threshold mechanics used in the reveal and progress variants, see how IntersectionObserver threshold works in practice.

FAQ

Related

• Building a Sticky Header with IntersectionObserver
• Scroll-Spy Navigation with IntersectionObserver
• Dynamic Visibility Tracking
• IntersectionObserver API Deep Dive
• How IntersectionObserver threshold works in practice

↑ Back to Implementation Patterns for Viewport & Resize Tracking