JavaScript Document scrollsnapchange Event

What You’ll Learn

The Document scrollsnapchange event fires when a new scroll snap target is selected at the end of a scrolling operation on the document. Learn CSS setup on html, SnapEvent.snapTargetBlock, and five try-it labs.

Introduction

CSS scroll snap can make sections “lock” into place as the user scrolls—like full-page slides. When the document itself is the snap container and a new target is chosen after scrolling ends, the browser fires scrollsnapchange on the Document.

Unlike plain scroll or scrollend, this event tells you which element became the selected snap target via a SnapEvent.

Understanding Document scrollsnapchange

A Document event that answers: “Did scrolling end with a newly selected snap target on the document container?”

• Fires on the document scroll container when a new snap target is selected at the end of scrolling (MDN).
• Requires the HTML document as snap container (scroll-snap-type on html).
• Event type — SnapEvent (inherits from Event).
• Useful properties — event.snapTargetBlock (and snapTargetInline when relevant).
• Handler — document.onscrollsnapchange or addEventListener("scrollsnapchange", ...).
• Status — Experimental and Limited availability on MDN (not Baseline).

📝 Syntax

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

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

onscrollsnapchange = (event) => { };

Event type

A SnapEvent, which inherits from the generic Event type.

MDN-style handler

document.addEventListener("scrollsnapchange", (event) => {
  event.snapTargetBlock.classList.add("selected");
});

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 newly selected section.

⚖️ scrollsnapchange vs scrollend vs scroll

MDN also documents related scrollsnapchanging (selection in progress). Treat that as a sibling experimental snap event when you need live preview while scrolling.

Examples Gallery

Examples follow MDN Document: scrollsnapchange event. Labs use document-level CSS snap. Support is limited—feature-detect and scroll to snap.

document.addEventListener("scrollsnapchange", (event) => {
  document.querySelectorAll(".selected").forEach((el) => {
    el.classList.remove("selected");
  });
  if (event.snapTargetBlock) {
    event.snapTargetBlock.classList.add("selected");
  }
});

Scroll snaps to a section
That section gets class "selected"

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

document.onscrollsnapchange = (event) => {
  const t = event.snapTargetBlock;
  out.textContent = t
    ? "Snapped to #" + (t.id || t.tagName)
    : "scrollsnapchange (no snapTargetBlock)";
};

Snapped to #slide-2

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

out.textContent = supported
  ? "scrollsnapchange supported — scroll to snap"
  : "scrollsnapchange missing — CSS snap may still work";

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

scrollsnapchange supported — scroll to snap
(or) scrollsnapchange missing — CSS snap may still work

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

document.addEventListener("scrollsnapchange", (event) => {
  const t = event.snapTargetBlock;
  if (!t) return;
  label.textContent =
    t.dataset.title || t.getAttribute("aria-label") || t.id || "Section";
});

Features

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

document.addEventListener("scrollend", () => {
  out.textContent = "scrollend @ Y=" + Math.round(window.scrollY);
});

if ("onscrollsnapchange" in document) {
  document.addEventListener("scrollsnapchange", (event) => {
    const id = event.snapTargetBlock && event.snapTargetBlock.id;
    out.textContent =
      "scrollsnapchange → #" + id + " (Y=" + Math.round(window.scrollY) + ")";
  });
}

scrollsnapchange → #slide-3 (Y=1440)

🚀 Common Use Cases

• Highlighting the active full-page section after snap.
• Updating a sticky caption / progress dots for slideshow layouts.
• Analytics for which snap slide users land on.
• Triggering section animations only when a snap target is selected.
• Teaching CSS scroll snap + progressive JS enhancement.

🔧 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: scrollsnapchanging, scrollend, scroll, JavaScript hub.

💡 Best Practices