IntersectionObserver API Explained — Lazy Loading, Scroll Animations & Real Patterns

// --- Basic IntersectionObserver setup ---
// We want to know when a 'feature card' enters the viewport

const featureCard = document.querySelector('.feature-card');

// The callback receives an array of entries (one per observed element)
// and a reference back to the observer itself
const handleIntersection = (entries, observer) => {
  entries.forEach(entry => {
    // entry.isIntersecting = true means the element is visible in the root
    console.log('Element:', entry.target);
    console.log('Is visible:', entry.isIntersecting);
    // intersectionRatio is 0.0 - 1.0: how much of the element is visible
    console.log('Visible ratio:', entry.intersectionRatio.toFixed(2));
    // boundingClientRect gives the element's position in the viewport
    console.log('Top from viewport:', entry.boundingClientRect.top);
  });
};

const observerOptions = {
  // root: null means we use the browser viewport as the container
  root: null,
  // rootMargin: '0px' means no expansion/shrinking of the root boundary
  rootMargin: '0px',
  // threshold: 0.1 means fire the callback when 10% of the element is visible
  threshold: 0.1
};

// Create the observer by passing the callback and options
const intersectionObserver = new IntersectionObserver(
  handleIntersection,
  observerOptions
);

// Start watching the feature card
// Nothing happens until the element actually crosses the threshold
intersectionObserver.observe(featureCard);

console.log('Observer is watching. Scroll to reveal the feature card.');

// To stop watching an element (important for cleanup):
// intersectionObserver.unobserve(featureCard);

// To destroy the observer entirely and free memory:
// intersectionObserver.disconnect();

// HTML structure expected:
// <img class="lazy-image" data-src="/images/product-1.jpg" alt="Product 1" />
// src is intentionally empty — we fill it in when the image is near the viewport

const lazyImages = document.querySelectorAll('img.lazy-image');

const loadImage = (imageElement) => {
  const realSrc = imageElement.dataset.src;

  if (!realSrc) {
    // Guard against images that don't have a data-src attribute
    console.warn('Lazy image is missing data-src attribute:', imageElement);
    return;
  }

  // Swapping src triggers the browser to fetch the real image
  imageElement.src = realSrc;

  // Optional: remove the data-src so we can tell at a glance it's been loaded
  imageElement.removeAttribute('data-src');

  // Add a CSS class so we can animate the image in with a fade
  imageElement.classList.add('image-loaded');
};

const lazyLoadCallback = (entries, observer) => {
  entries.forEach(entry => {
    if (!entry.isIntersecting) {
      // The image isn't visible yet — do nothing
      return;
    }

    // The image has entered our 'pre-load zone' — load it now
    loadImage(entry.target);

    // CRITICAL: Stop watching this image — it only needs to load once
    // Without this, the observer keeps firing and wastes resources
    observer.unobserve(entry.target);
  });
};

const lazyImageObserver = new IntersectionObserver(lazyLoadCallback, {
  root: null,
  // Load images 200px BEFORE they enter the viewport
  // This prevents users ever seeing a blank image placeholder
  rootMargin: '0px 0px 200px 0px',
  threshold: 0
});

// Register every lazy image with the observer
lazyImages.forEach(image => {
  lazyImageObserver.observe(image);
});

console.log(`Watching ${lazyImages.length} images for lazy loading.`);

// CSS to pair with this (add to your stylesheet):
// .lazy-image { opacity: 0; transition: opacity 0.4s ease; }
// .lazy-image.image-loaded { opacity: 1; }

// ============================================================
// PATTERN A: Scroll-triggered section animations
// ============================================================
// HTML: <section class="animate-on-scroll" id="about">...</section>
// CSS:  .animate-on-scroll { opacity: 0; transform: translateY(30px); transition: all 0.6s ease; }
//       .animate-on-scroll.is-visible { opacity: 1; transform: translateY(0); }

const animatableSections = document.querySelectorAll('.animate-on-scroll');

const animationObserver = new IntersectionObserver(
  (entries) => {
    entries.forEach(entry => {
      if (entry.isIntersecting) {
        // Add class to trigger CSS transition
        entry.target.classList.add('is-visible');
        // Stop watching once animated — we don't want to reverse the animation
        animationObserver.unobserve(entry.target);
      }
    });
  },
  {
    root: null,
    // Trigger when 15% of the section is visible — feels more natural than 0
    threshold: 0.15
  }
);

animatableSections.forEach(section => animationObserver.observe(section));


// ============================================================
// PATTERN B: Active navigation link highlighting
// ============================================================
// HTML: <nav><a href="#about" class="nav-link" data-target="about">About</a></nav>
//       <section id="about">...</section>

const pageSections = document.querySelectorAll('section[id]');
const navLinks = document.querySelectorAll('.nav-link[data-target]');

// Build a lookup map: sectionId -> navLink element for O(1) access
const navLinkMap = {};
navLinks.forEach(link => {
  navLinkMap[link.dataset.target] = link;
});

const setActiveNavLink = (activeSectionId) => {
  // Remove active state from all links first
  navLinks.forEach(link => link.classList.remove('active-link'));

  // Set active state only on the matching link
  const matchingLink = navLinkMap[activeSectionId];
  if (matchingLink) {
    matchingLink.classList.add('active-link');
  }
};

const navHighlightObserver = new IntersectionObserver(
  (entries) => {
    entries.forEach(entry => {
      if (entry.isIntersecting) {
        // When a section enters the 'active zone', highlight its nav link
        setActiveNavLink(entry.target.id);
      }
    });
  },
  {
    root: null,
    // This is the magic: shrink the root to a thin band around the middle
    // of the viewport. A section is 'active' when it crosses this band.
    // '-40% 0px -40% 0px' means: ignore the top 40% and bottom 40%
    rootMargin: '-40% 0px -40% 0px',
    threshold: 0
  }
);

pageSections.forEach(section => navHighlightObserver.observe(section));

console.log('Scroll observers ready: animations and nav highlighting active.');

// CSS for nav highlight:
// .nav-link { color: #666; transition: color 0.3s; }
// .nav-link.active-link { color: #007bff; font-weight: bold; }

// ============================================================
// PATTERN: Reading progress indicator using threshold array
// ============================================================
// Fires at every 5% increment as the article scrolls through the viewport

const articleBody = document.querySelector('.article-body');
const progressBar = document.querySelector('.reading-progress-bar');

// Generate thresholds at every 5% step: [0, 0.05, 0.10, ... , 1.0]
const buildThresholdList = (steps) => {
  const thresholds = [];
  for (let step = 0; step <= steps; step++) {
    thresholds.push(step / steps);
  }
  return thresholds;
};

const readingProgressObserver = new IntersectionObserver(
  (entries) => {
    entries.forEach(entry => {
      // intersectionRatio is 0.0 - 1.0: use it directly as a percentage
      const visiblePercent = Math.round(entry.intersectionRatio * 100);
      progressBar.style.width = `${visiblePercent}%`;
      progressBar.setAttribute('aria-valuenow', visiblePercent);
      console.log(`Reading progress: ${visiblePercent}%`);
    });
  },
  {
    root: null,
    rootMargin: '0px',
    // Fire the callback at every 5% of visibility
    threshold: buildThresholdList(20)
  }
);

readingProgressObserver.observe(articleBody);


// ============================================================
// CLEANUP EXAMPLE: React-style cleanup
// ============================================================
// In a real React component this would live inside a useEffect:
const setupObserverWithCleanup = (targetElement) => {
  const observer = new IntersectionObserver(
    (entries) => {
      if (entries[0].isIntersecting) {
        console.log('Component entered viewport');
        // do your work...
      }
    },
    { threshold: 0.1 }
  );

  observer.observe(targetElement);

  // Return a cleanup function — call this when the component unmounts
  // Failing to do this causes memory leaks in SPA frameworks
  return () => {
    console.log('Cleaning up observer — disconnecting to free memory');
    observer.disconnect();
  };
};

// Usage pattern in React:
// useEffect(() => {
//   const cleanup = setupObserverWithCleanup(myRef.current);
//   return cleanup; // React calls this when the component unmounts
// }, []);