JavaScript Document scroll Event

What You’ll Learn

The Document scroll event fires when the document view has been scrolled. Learn how to read window.scrollY, use document.onscroll, throttle handlers the MDN way with setTimeout, and when to prefer IntersectionObserver or scrollend—with five try-it labs.

Introduction

When the user scrolls the page (or you call APIs that move the document view), the browser fires a scroll event on the Document. That is the signal for sticky headers, progress bars, “back to top” buttons, and parallax-style UI.

Scroll is busy: handlers can run many times per second. MDN warns that expensive DOM work inside every scroll callback can cause jank. Keep the listener light, and throttle work that must update the UI.

Understanding Document scroll

A standard Document event that answers: “Did the document view just scroll?”

• Fires when the document view has been scrolled (MDN).
• Event type — a generic Event.
• Handler — document.onscroll or addEventListener("scroll", ...).
• Position — read window.scrollY / scrollX (or scrollingElement.scrollTop).
• Performance — throttle expensive work; MDN prefers measuring timeouts with setTimeout.
• Status — Baseline Widely available since July 2015 (MDN).

📝 Syntax

Use the event name with addEventListener, or set the handler property:

addEventListener("scroll", (event) => { });

onscroll = (event) => { };

Event type

A generic Event.

Minimal listener

document.addEventListener("scroll", () => {
  console.log("scrollY:", window.scrollY);
});

⚡ Why Throttle Scroll Handlers?

MDN: scroll can fire at a high rate. Do not run heavy DOM modifications on every event. If fast scrolling feels janky, throttle.

• Do measure your own interval with setTimeout (MDN example uses ~20ms).
• Avoid thinking requestAnimationFrame alone throttles scroll—MDN notes animation frame callbacks fire at a similar rate.
• Consider IntersectionObserver for “did this section enter the viewport?” instead of scroll math.

⚖️ Document scroll vs Element scroll vs scrollend

Examples Gallery

Examples follow MDN Document: scroll event. Try-it labs include tall content so you can scroll and see updates.

const out = document.getElementById("out");

document.addEventListener("scroll", () => {
  out.textContent = "scrollY: " + Math.round(window.scrollY);
});

scrollY: 240

const out = document.getElementById("out");

document.onscroll = () => {
  out.textContent =
    "onscroll → Y=" + Math.round(window.scrollY) +
    " X=" + Math.round(window.scrollX);
};

onscroll → Y=120 X=0

let lastKnownScrollPosition = 0;
let ticking = false;
const out = document.getElementById("out");

function doSomething(scrollPos) {
  out.textContent = "Throttled work @ " + Math.round(scrollPos);
}

document.addEventListener("scroll", () => {
  lastKnownScrollPosition = window.scrollY;

  if (!ticking) {
    setTimeout(() => {
      doSomething(lastKnownScrollPosition);
      ticking = false;
    }, 20);

    ticking = true;
  }
});

Throttled work @ 360

const bar = document.getElementById("bar");
const label = document.getElementById("label");

function updateProgress() {
  const doc = document.documentElement;
  const max = doc.scrollHeight - doc.clientHeight;
  const pct = max > 0 ? Math.min(100, (window.scrollY / max) * 100) : 0;
  bar.style.width = pct + "%";
  label.textContent = Math.round(pct) + "% read";
}

document.addEventListener("scroll", updateProgress, { passive: true });
updateProgress();

48% read
(progress bar width updates)

const btn = document.getElementById("top");

document.addEventListener("scroll", () => {
  btn.hidden = window.scrollY < 200;
}, { passive: true });

btn.addEventListener("click", () => {
  window.scrollTo({ top: 0, behavior: "smooth" });
});

Button hidden near top
Button appears after ~200px scroll
Click → smooth scroll to top

🚀 Common Use Cases

• Sticky / shrinking headers that react to scroll position.
• Reading progress indicators on long articles.
• “Back to top” and floating action buttons.
• Lazy UI that loads more content near the bottom (with care / IntersectionObserver).
• Teaching high-frequency events and throttling.

🔧 How It Works

📝 Notes

• Baseline Widely available (since July 2015)—no Deprecated / Experimental / Non-standard banner.
• Keep handlers light; throttle with setTimeout per MDN guidance.
• Element overflow scrolling uses Element scroll, not Document scroll.
• For “scrolling finished,” see Document scrollend.
• Related learning: scrollingElement, scrollTop, JavaScript hub.

💡 Best Practices