JavaScript Document scrollsnapchanging Event

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

Definition

In JavaScript, scrollsnapchanging fires on the document scroll container when the browser decides a new snap target is pending — it will be selected when the current scroll gesture ends (MDN). The document must be the snap container (scroll-snap-type on html).

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

Syntax

Listen for scrollsnapchanging. Start with this line.

JavaScript
document.addEventListener("scrollsnapchanging", handler)
CallWhat it does
document.addEventListener("scrollsnapchanging", handler)Primary signature.

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

Library declarations
JavaScript
document.addEventListener("scrollsnapchanging", handler)

Parameters

ParameterDescription
CSS snap on htmlRequired. Makes Document the snap container
ListenerRequired. addEventListener or onscrollsnapchanging

Return Value

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

JavaScript Examples

Example 1 — Mark Pending Target (MDN)

Highlight the section that will snap when the gesture ends.

JavaScript
document.addEventListener("scrollsnapchanging", (event) => {
  document.querySelectorAll(".pending").forEach((el) => {
    el.classList.remove("pending");
  });
  if (event.snapTargetBlock) {
    event.snapTargetBlock.classList.add("pending");
  }
});
Try It Yourself

How It Works

  1. Listen on document. Needs CSS snap on html (MDN).
  2. Clear old pending classes. Only one pending target at a time.
  3. Read snapTargetBlock. The child that will be selected.
  4. Add pending. Style the preview target while the gesture continues.

Example 2 — vs scrollsnapchange

Pending during the gesture; selected when scrolling settles.

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

document.addEventListener("scrollsnapchanging", (event) => {
  const id = event.snapTargetBlock && event.snapTargetBlock.id;
  out.textContent = "pending → #" + id;
});

document.addEventListener("scrollsnapchange", (event) => {
  const id = event.snapTargetBlock && event.snapTargetBlock.id;
  out.textContent = "selected → #" + id;
});
Try It Yourself

How It Works

  1. Listen for both events. Same SnapEvent shape.
  2. changing first. Pending target while the user still scrolls.
  3. change second. Final selected target after the gesture ends.
  4. Use both for preview UI, then a settled “selected” state.

Example 3 — Feature Detect

Check support before relying on the Experimental event.

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

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

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

How It Works

  1. Probe the handler property. "onscrollsnapchanging" in document.
  2. Tell the user. CSS snap can work even when the JS event is missing.
  3. Attach only if supported. Progressive enhancement (MDN guidance).
  4. Keep CSS first. The event is optional UI sugar.
Compatibility

Browser Support

Document scrollsnapchanging is marked Experimental and Limited availability on MDN (not Baseline). Logos use the shared browser-image-sprite.png sprite from this project. Feature-detect and keep CSS snap usable without the event.

✓ Experimental · Limited availability

Document scrollsnapchanging

Fires when a new scroll snap target is pending on the document snap container.

Limited Check compat
Google Chrome Check BCD / Chromium scroll snap events
Partial
Mozilla Firefox Limited / check BCD
Limited
Apple Safari Limited / check BCD
Limited
Microsoft Edge Follow Chromium (check BCD)
Partial
Opera Follow Chromium behavior
Partial
Internet Explorer No scrollsnapchanging
Not supported
scrollsnapchanging Limited availability

Bottom line: Set scroll-snap-type on html, listen for scrollsnapchanging, read SnapEvent.snapTargetBlock, and feature-detect before production. See the MDN Document scrollsnapchanging reference.

Frequently Asked Questions

It fires on the scroll container when the browser determines a new scroll snap target is pending — it will be selected when the current scroll gesture ends (MDN). The Document must be the snap container (scroll-snap-type on html).
MDN marks Document scrollsnapchanging as Experimental and Limited availability (not Baseline). It is not Deprecated or Non-standard. Feature-detect before production use.
scrollsnapchanging means a snap target is pending during the gesture. scrollsnapchange means a new snap target was selected at the end of the scrolling operation.
A SnapEvent, which inherits from Event. Use event.snapTargetBlock (and snapTargetInline when relevant) for the pending snap target element.
MDN’s example removes old pending classes, then adds pending to event.snapTargetBlock so only the current pending target is highlighted.
Same idea for an Element snap container. Document scrollsnapchanging is for when html is the scroll snap container.

Next: Document securitypolicyviolation

Learn how Content Security Policy violations surface as Document events.

securitypolicyviolation 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 scrollsnapchange Event JavaScript Document securitypolicyviolation Event