JavaScript Document scrollsnapchanging Event

What You’ll Learn

The Document scrollsnapchanging event fires when the browser decides a new scroll snap target is pending (it will be selected when the current gesture ends). Learn CSS setup on html, the MDN pending class pattern, and five try-it labs.

Introduction

While the user is mid-gesture, the browser may already know which section will snap when they let go. That upcoming choice is a pending snap target—and that is when Document scrollsnapchanging fires.

Pair it with scrollsnapchange for the final selection after the scrolling operation ends. Both use SnapEvent.

Understanding Document scrollsnapchanging

A Document event that answers: “Is a new snap target pending for when this gesture ends?”

• Fires when the browser determines a new scroll snap target is pending (MDN).
• Pending means it will be selected when the current scroll gesture ends.
• Requires the HTML document as snap container (scroll-snap-type on html).
• Event type — SnapEvent (inherits from Event).
• Handler — document.onscrollsnapchanging or addEventListener("scrollsnapchanging", ...).
• Status — Experimental and Limited availability on MDN (not Baseline).

📝 Syntax

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

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

onscrollsnapchanging = (event) => { };

Event type

A SnapEvent, which inherits from the generic Event type.

MDN-style handler

document.addEventListener("scrollsnapchanging", (event) => {
  // remove previously-set "pending" classes
  const pendingElems = document.querySelectorAll(".pending");
  pendingElems.forEach((elem) => {
    elem.classList.remove("pending");
  });

  // Set current pending snap target class to "pending"
  event.snapTargetBlock.classList.add("pending");
});

Minimal CSS setup (Document as snap container)

html {
  scroll-snap-type: block mandatory;
}

section {
  scroll-snap-align: start;
  min-height: 100vh;
}

🔍 What Is a SnapEvent?

SnapEvent extends Event with snap-target references so you can style or announce the pending snap target during a gesture.

⚖️ scrollsnapchanging vs scrollsnapchange

Also compare scrollend (scrolling finished) and scroll (continuous movement).

Examples Gallery

Examples follow MDN Document: scrollsnapchanging event. Labs use document-level CSS snap. Support is limited—feature-detect and scroll mid-gesture to see pending targets.

document.addEventListener("scrollsnapchanging", (event) => {
  const pendingElems = document.querySelectorAll(".pending");
  pendingElems.forEach((elem) => {
    elem.classList.remove("pending");
  });

  event.snapTargetBlock.classList.add("pending");
});

While scrolling toward a section
That section gets class "pending"

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

document.onscrollsnapchanging = (event) => {
  const t = event.snapTargetBlock;
  out.textContent = t
    ? "Pending #" + (t.id || t.tagName)
    : "scrollsnapchanging (no snapTargetBlock)";
};

Pending #slide-2

const out = document.getElementById("out");
const supported = "onscrollsnapchanging" in document;

out.textContent = supported
  ? "scrollsnapchanging supported — scroll toward a snap"
  : "scrollsnapchanging missing — CSS snap may still work";

if (supported) {
  document.addEventListener("scrollsnapchanging", (event) => {
    out.textContent =
      "Pending: " + (event.snapTargetBlock && event.snapTargetBlock.id);
  });
}

scrollsnapchanging supported — scroll toward a snap
(or) scrollsnapchanging missing — CSS snap may still work

function clearClass(name) {
  document.querySelectorAll("." + name).forEach((el) => el.classList.remove(name));
}

if ("onscrollsnapchanging" in document) {
  document.addEventListener("scrollsnapchanging", (event) => {
    clearClass("pending");
    event.snapTargetBlock?.classList.add("pending");
  });
}

if ("onscrollsnapchange" in document) {
  document.addEventListener("scrollsnapchange", (event) => {
    clearClass("pending");
    clearClass("selected");
    event.snapTargetBlock?.classList.add("selected");
  });
}

During gesture → pending outline
After settle → selected outline

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

document.addEventListener("scrollsnapchanging", (event) => {
  const t = event.snapTargetBlock;
  if (!t) return;
  label.textContent =
    "Pending: " + (t.dataset.title || t.id || "section");
});

Pending: Features

🚀 Common Use Cases

• Previewing which section will snap while the user is still scrolling.
• Updating a “next snap” caption during the gesture.
• Soft highlighting before the final scrollsnapchange commit.
• Pairing pending + selected styles for clearer snap feedback.
• Teaching pending vs selected scroll snap events.

🔧 How It Works

📝 Notes

• MDN: Experimental and Limited availability—Experimental banner shown above.
• Not Deprecated or Non-standard.
• Document event needs snap on html; Element overflow snap uses Element events.
• CSS snap can work without JS—use the event for enhancement only.
• Related learning: securitypolicyviolation, scrollsnapchange, JavaScript hub.

💡 Best Practices