JavaScript Scrolling | W3docs JavaScript Tutorial

Understanding JavaScript Scrolling Events and Techniques

Scrolling events in JavaScript let you react to where a user is on a page. This is the foundation for features such as parallax effects, triggering animations based on scroll position, implementing infinite scroll, "back to top" buttons, sticky headers, and reading-progress bars. This guide covers how to read the current scroll position, how to scroll programmatically, how to handle the scroll event efficiently, and when to reach for the modern IntersectionObserver instead.

Reading the Current Scroll Position

Before reacting to scrolling you usually need to know how far the page has scrolled. The most reliable properties are on the window:

window.scrollY — vertical scroll distance in pixels (also window.pageYOffset, an older alias).
window.scrollX — horizontal scroll distance in pixels (alias window.pageXOffset).

For a single scrollable element, use element.scrollTop and element.scrollLeft instead. These are read/write: assigning to them jumps the element to that position.

// How far down the whole page has the user scrolled?
console.log(window.scrollY); // e.g. 0 at the top, 420 partway down

// Total scrollable height of the document
const docHeight = document.documentElement.scrollHeight;
const winHeight = window.innerHeight;

// How close to the bottom are we (0 = top, 1 = bottom)?
const progress = window.scrollY / (docHeight - winHeight);
console.log(progress);

For per-element offsets and a deeper look at getBoundingClientRect, see JavaScript Coordinates and Window Sizes and Scrolling.

Scrolling Programmatically

You don't only listen for scrolling — you can also trigger it. These methods accept a behavior: 'smooth' option for an animated transition instead of an instant jump:

window.scrollTo(x, y) — scroll to an absolute position.
window.scrollBy(dx, dy) — scroll by a relative amount from the current position.
element.scrollIntoView(options) — scroll so a specific element is visible.

// Jump to the very top, smoothly
window.scrollTo({ top: 0, left: 0, behavior: 'smooth' });

// Nudge down by one viewport height
window.scrollBy({ top: window.innerHeight, behavior: 'smooth' });

// Bring an element into view (e.g. after navigating to an anchor)
document.querySelector('#section-2')
  .scrollIntoView({ behavior: 'smooth', block: 'start' });

This is the proper way to implement a "back to top" button or smooth in-page anchor navigation. Use querySelector to grab the target element first.

The JavaScript Scroll Event

The scroll event fires when the document view or a scrollable element is scrolled. It is one of the most frequently used events for dynamic, interactive designs.

Key Concepts

Event Frequency: The scroll event can fire dozens of times per second, so its handler runs very often. Doing heavy work (layout reads, DOM writes, network calls) on every fire causes janky scrolling. The standard fix is to throttle or debounce the handler.
window vs. element scrolling: You can listen for scroll on the whole window (window.addEventListener('scroll', ...)) or on a specific overflow-scrollable element (el.addEventListener('scroll', ...)).
scroll does not bubble: A scroll event on an element does not bubble up to the document, so attach the listener to the element that actually scrolls.

Throttle vs. Debounce

Both limit how often your handler runs, but they behave differently:

Debounce waits until scrolling stops for wait ms, then runs once. Good for "do something when the user finishes scrolling" (e.g. save scroll position).
Throttle runs at most once every wait ms during scrolling. Better for continuous effects like progress bars, where you want regular updates while scrolling.

function debounce(func, wait) {
  let timeout;
  return function (...args) {
    clearTimeout(timeout);
    timeout = setTimeout(() => func.apply(this, args), wait);
  };
}

function throttle(func, wait) {
  let last = 0;
  return function (...args) {
    const now = Date.now();
    if (now - last >= wait) {
      last = now;
      func.apply(this, args);
    }
  };
}

// Debounce: runs once 100ms after scrolling stops
window.addEventListener('scroll', debounce(() => {
  // handle scroll logic here
}, 100));

// Throttle: runs at most every 100ms while scrolling
window.addEventListener('scroll', throttle(() => {
  // update a progress bar, etc.
}, 100));

Both setTimeout-based helpers build on the setTimeout / setInterval scheduling APIs.

Practical Examples of Scroll Event Handling

This example demonstrates how to hide a navigation bar when scrolling down and show it when scrolling up, which is a common pattern in many modern websites to maximize screen real estate.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Scroll Event Navigation Example</title>
    <style>
      #navbar {
        position: fixed;
        top: 0;
        width: 100%;
        background-color: #333;
        color: white;
        text-align: center;
        padding: 10px;
        transition: top 0.3s;
      }
      body {
        padding: 0;
        margin: 0;
        height: 1500px; /* to ensure scrolling */
        font-family: Arial, sans-serif;
      }
    </style>
  </head>
  <body>
    <p style="display: flex; justify-content: center; align-items: center; margin-top: 50vh;"><strong>When you scroll down, the navigation bar disappears. Scroll back up, and it reappears!</strong></p>

    <div id="navbar">Navigation Bar</div>

    <script>
      let lastScrollTop = 0;
      window.addEventListener(
        "scroll",
        function () {
          let currentScroll = window.pageYOffset || document.documentElement.scrollTop;
          if (currentScroll > lastScrollTop) {
            document.getElementById("navbar").style.top = "-50px"; // Adjust based on nav height
          } else {
            document.getElementById("navbar").style.top = "0px";
          }
          lastScrollTop = currentScroll <= 0 ? 0 : currentScroll; // For Mobile or negative scrolling
        },
        false
      );
    </script>
  </body>
</html>

Try it Yourself »

Explanation:

The script tracks the last scroll position and compares it with the current scroll position. If the current position is higher, it means the user is scrolling down, so the navigation bar is hidden by adjusting its top position off-screen.
When scrolling up, the navigation bar reappears.

Example 2: Scroll Animation Trigger

This example shows how you can trigger animations when elements enter the viewport during a scroll.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8" />
    <title>Scroll Animation Trigger</title>
    <style>
        .box {
            width: 100px;
            height: 100px;
            background: red;
            opacity: 0;
            transition: opacity 2s;
            margin: 600px auto;  /* Ensures it starts out of view */
        }
    </style>
</head>
<body>
<p>Keep scrolling down to see the animation!</p>
<div class="box"></div>

<script>
    let hasAnimated = false;
    window.addEventListener('scroll', function() {
        const box = document.querySelector('.box');
        const rect = box.getBoundingClientRect();
        
        if (rect.top < window.innerHeight && !hasAnimated) {
            box.style.opacity = 1;  // Fade in the box when it comes into view
            hasAnimated = true;
        }
    });
</script>
</body>
</html>

Try it Yourself »

Explanation:

Visibility Check: The script checks if the .box element's top is within the viewport and changes its opacity to 1, triggering a fade-in effect. A flag prevents the animation from re-triggering on subsequent scroll events.

Example 3: Parallax Scrolling Effect

This example demonstrates a simple parallax effect where the background image moves at a different speed than the foreground content as you scroll down the page.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8" />
    <title>Enhanced Parallax Scrolling</title>
    <style>
        body, html {
            height: 100%;
            margin: 0;
            font-family: Arial, sans-serif;
            overflow-x: hidden; /* Prevent horizontal scroll */
        }
        .parallax {
            height: 100vh; /* Full height of the viewport */
            position: relative;
            background: url('https://via.placeholder.com/1920x1080') no-repeat center center; 
            background-size: cover;
            display: flex;
            justify-content: center;
            align-items: center;
            color: white;
            font-size: 36px;
            letter-spacing: 1px;
        }
        .content {
            height: 100vh;
            display: flex;
            align-items: center;
            justify-content: center;
            background: white;
            color: #333;
            font-size: 24px;
            padding: 0 20px;
            text-align: center;
            box-sizing: border-box;
            border-top: 1px solid #ccc;
            border-bottom: 1px solid #ccc;
        }
    </style>
</head>
<body>

<div class="content">Scroll down to see the parallax effect!</div>
<div class="parallax">Stunning Parallax!</div>
<div class="content">Keep scrolling to see more effects.</div>
<div class="parallax"></div>
<div class="content">You have reached the end. Amazing, right?</div>

<script>
    document.addEventListener('scroll', function() {
        document.querySelectorAll('.parallax').forEach(function(el) {
            const factor = 0.5; // Change this for more or less parallax
            const offset = window.pageYOffset * factor - 300; // Adjusts the starting position of background
            el.style.backgroundPositionY = offset + 'px';
        });
    });
</script>

</body>
</html>

Try it Yourself »

Explanation:

CSS Styles: The .parallax class sets the background image to fill the container and centers it. The example relies entirely on JavaScript for positioning, avoiding CSS background-attachment: fixed, which can cause performance issues on mobile devices.
JavaScript Functionality: On scroll, the script calculates a new vertical position for the background image from the scroll offset. By adjusting backgroundPositionY dynamically, the image shifts at a different rate than the page content, creating the parallax depth effect.

In summary, as you scroll the background images move slower than the text, making them appear to sit at a different depth.

The Modern Alternative: IntersectionObserver

For the common case of "do something when an element becomes visible" (lazy loading, fade-in animations, infinite scroll), IntersectionObserver is the recommended modern approach. Instead of running your code on every scroll event and manually reading positions, the browser tells you asynchronously when an element crosses a threshold — far more efficient and jank-free.

const observer = new IntersectionObserver(
  (entries) => {
    entries.forEach((entry) => {
      if (entry.isIntersecting) {
        entry.target.classList.add('visible'); // run once it enters view
        observer.unobserve(entry.target);      // stop watching it
      }
    });
  },
  { threshold: 0.25 } // fire when 25% of the element is visible
);

document.querySelectorAll('.box').forEach((el) => observer.observe(el));

Reach for the scroll event when you need a continuous readout of scroll position (parallax, progress bars). Reach for IntersectionObserver when you only care that an element entered or left the viewport. It is conceptually similar to the MutationObserver API.

Preventing and Restoring Scroll

A common UI requirement is locking page scroll while a modal or menu is open. You cannot reliably cancel the scroll event with preventDefault() (it fires after scrolling has happened). Instead, toggle CSS overflow:

// Lock scrolling (e.g. when opening a modal)
document.body.style.overflow = 'hidden';

// Restore it when the modal closes
document.body.style.overflow = '';

Conclusion

Handling scroll events effectively is a crucial skill for web developers, enabling more interactive and performance-optimized websites. Whether you're implementing user interface enhancements like dynamic navigation bars or using a parallax effect on your page, understanding and correctly handling scrolling in JavaScript can drastically improve the user experience.

Practice

Which actions are appropriate uses of the JavaScript scroll event in web development?

Implementing dynamic effects such as showing or hiding elements based on scroll position.Changing the font size of the webpage content dynamically as the user scrolls.Triggering animations when certain parts of the webpage become visible on scrolling.Disabling the scrolling functionality completely on specific sections of a webpage.Adjusting the scroll speed of the webpage to create a slow-motion scrolling effect.

Understanding JavaScript Scrolling Events and Techniques

Reading the Current Scroll Position

Scrolling Programmatically

The JavaScript Scroll Event

Key Concepts

Throttle vs. Debounce

Practical Examples of Scroll Event Handling

Example 1: Show/Hide Navigation on Scroll

Example 2: Scroll Animation Trigger

Example 3: Parallax Scrolling Effect

The Modern Alternative: IntersectionObserver

Preventing and Restoring Scroll

Conclusion

Practice