JavaScript Document scroll Event

Beginner
5 min read
Updated: Nov 2026
3 examples
Event
Decorative image with the word SCROLL

Definition

In JavaScript, the Document scroll event fires when the document view has been scrolled (MDN). Read position with window.scrollY / scrollX. A generic Event.

Register a listener with addEventListener. Check readiness and browser support before you rely on this event.

Syntax

Listen for scroll. Start with this line.

JavaScript
addEventListener("scroll", fn)
CallWhat it does
addEventListener("scroll", fn)Primary signature.

Built into the browser. Listen with document.addEventListener("scroll", …) — no import required.

Library declarations
JavaScript
addEventListener("scroll", fn)

Parameters

ParameterDescription
Listener on documentRequired. Document-view scroll signal
Throttle (setTimeout)Optional. Limit work rate (MDN)

Return Value

Return ValueDescription
*Fires as a Document event (listener receives the Event object).

JavaScript Examples

Example 1 — Log scrollY

Show the vertical scroll position whenever the document view scrolls.

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

console.log("scroll listener attached");
Try It Yourself

How It Works

  1. Listen on document. Fires when the document view scrolls (MDN).
  2. Read scrollY. Vertical pixels from the top of the page.
  3. Round for display. Optional — positions can be fractional.
  4. Keep it light. Logging is fine; heavy DOM work needs throttling.

Example 2 — Throttle with setTimeout

MDN pattern: store position on every scroll; run work at most every 20ms.

JavaScript
let lastKnownScrollPosition = 0;
let ticking = false;

function doSomething(scrollPos) {
  console.log("Throttled work @", Math.round(scrollPos));
}

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

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

How It Works

  1. Always save position. Every scroll updates lastKnownScrollPosition.
  2. Schedule once. ticking prevents stacking many timers.
  3. Work later. After 20ms, run doSomething with the latest position.
  4. Why not only rAF? MDN: animation frames fire at a similar rate to scroll.

Example 3 — Back to Top After 200px

Toggle a control from scroll position; jump back with scrollTo.

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

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

  { passive: true }
);

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

How It Works

  1. Compare scrollY. Show the button only after ~200px.
  2. Passive listener. Scroll handlers often do not call preventDefault.
  3. Click to reset. scrollTo({ top: 0, behavior: "smooth" }).
  4. Keep the check cheap. A boolean toggle is fine on every scroll.
Compatibility

Browser Support

Document scroll is Baseline Widely available (MDN, since July 2015). It is a standard Document event — not Deprecated, Experimental, or Non-standard.

✓ Baseline · Widely available

Document scroll

Fires when the document view has been scrolled. Pair with window.scrollY and throttle expensive work.

99% Modern browser support
Google Chrome Supported · Desktop & Mobile
Full support
Mozilla Firefox Supported · Desktop & Mobile
Full support
Apple Safari Supported · macOS & iOS
Full support
Microsoft Edge Supported · Chromium
Full support
Internet Explorer No native support · Use a polyfill
Polyfill
Opera Supported · Modern versions
Full support
Samsung Internet Supported · Android
Full support
Android WebView Supported · Modern WebView
Full support
Document scroll Excellent

Bottom line: Safe everywhere students build today. Keep handlers light, throttle with setTimeout when needed, and use scrollend or IntersectionObserver when that fits better.

Frequently Asked Questions

It fires when the document view has been scrolled. For element overflow scrolling, use the Element scroll event. To detect when scrolling has finished, see Document scrollend (MDN).
No. MDN marks Document scroll as Baseline Widely available (since July 2015). It is not Deprecated, Experimental, or Non-standard.
Scroll fires at a high rate. Avoid heavy DOM work on every event. MDN recommends throttling with setTimeout (measure your own timeout). Using requestAnimationFrame alone to throttle scroll is not useful because it runs at a similar rate.
Commonly use window.scrollY (and window.scrollX). You can also use document.scrollingElement.scrollTop for the scrolling root element.
Yes. You can use document.onscroll or document.addEventListener("scroll", …).
MDN suggests IntersectionObserver for threshold-based listening (for example, when a section enters the viewport) instead of computing visibility on every scroll event.

Next: scrollend

Learn the Document event that fires when scrolling has completed.

scrollend tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

11 people found this page helpful

JavaScript Document readystatechange Event JavaScript Document scrollend Event