Window: scrollsnapchanging — Ereignis · JavaScript-Referenz

Signatur

window.addEventListener("scrollsnapchanging", handler)

Beschreibung

Das Ereignis scrollsnapchanging gehört zur Scroll Snap Level 2-Erweiterung von CSS. Es wird am window ausgelöst, wenn der Wurzel-Scrollcontainer des Dokuments (also <html> mit scroll-snap-type) gescrollt wird und der Browser feststellt, dass sich das Element geändert hat, auf das er am Ende der aktuellen Geste einrasten würde. Das Ereignis sagt also voraus, wo das Scrollen voraussichtlich endet, bevor es dort ankommt.

Der Handler bekommt ein SnapEvent-Objekt. Dessen Eigenschaften snapTargetBlock und snapTargetInline enthalten das voraussichtliche Snap-Ziel in Block- bzw. Inline-Richtung. Gibt es in einer Achse kein Snap-Ziel, ist der Wert null.

Typische Anwendungsfälle:

Das kommende Ziel schon während des Wischens hervorheben, etwa bei Vollbild-Abschnitten oder Karussells.
Eine Navigation oder Seitenanzeige („3 / 5“) direkt beim Scrollen aktualisieren.
Inhalte vorab laden, die zum wahrscheinlichen Ziel gehören.

Das Gegenstück ist scrollsnapchange. Es feuert erst, wenn die Geste zu Ende ist und das Einrasten wirklich stattgefunden hat. scrollsnapchanging kann während einer Geste dagegen mehrmals feuern, zum Beispiel wenn der Nutzer hin und her wischt. Du registrierst das Ereignis entweder mit addEventListener() oder über die Eigenschaft window.onscrollsnapchanging.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Name des Ereignisses: `"scrollsnapchanging"`.
$handler Pflicht	(event: SnapEvent) => void		Callback, der ein `SnapEvent` mit `snapTargetBlock` und `snapTargetInline` (jeweils `Element \| null`) bekommt.
$options	boolean \| AddEventListenerOptions	false	Optionen wie `once`, `passive` oder `signal` (Abbruch über einen `AbortController`).

Rückgabewert

Typ

void

Beschreibung

addEventListener() gibt nichts zurück. Der Handler erhält ein SnapEvent. Das Ereignis lässt sich nicht abbrechen: preventDefault() hat keine Wirkung.

Beispiele

Kommenden Abschnitt schon beim Wischen hervorheben

// Vorbereitung: Das Dokument selbst rastet ein
document.documentElement.style.scrollSnapType = 'y mandatory';
document.querySelectorAll('section').forEach((s) => {
  s.style.scrollSnapAlign = 'start';
  s.style.minHeight = '100vh';
});

let previous = null;

window.addEventListener('scrollsnapchanging', (event) => {
  const target = event.snapTargetBlock;
  previous?.classList.remove('is-pending');
  if (target) {
    target.classList.add('is-pending');
    console.log('Voraussichtliches Ziel:', target.id);
  }
  previous = target;
});

Voraussichtliches Ziel: kapitel-2 Voraussichtliches Ziel: kapitel-3

Seitenanzeige über die on-Property aktualisieren

const sections = [...document.querySelectorAll('section')];
const indicator = document.querySelector('#indicator');

window.onscrollsnapchanging = (event) => {
  const index = sections.indexOf(event.snapTargetBlock);
  if (index !== -1) {
    indicator.textContent = `${index + 1} / ${sections.length}`;
  }
};

// Wieder entfernen:
// window.onscrollsnapchanging = null;

Mit Feature-Erkennung registrieren und per AbortController entfernen

const controller = new AbortController();

if ('onscrollsnapchanging' in window) {
  window.addEventListener('scrollsnapchanging', (e) => {
    console.log('pending:', e.snapTargetBlock?.id ?? 'kein Ziel');
  }, { signal: controller.signal });
} else {
  console.log('scrollsnapchanging wird nicht unterstützt – Fallback nutzen');
}

// Später, z. B. beim Verlassen der Ansicht:
const stopListening = () => controller.abort();

pending: kapitel-2

// Wichtig · Fallstricke

Browser-Unterstützung: Bisher nur in Chromium-Browsern (Chrome/Edge ab 129). Firefox und Safari unterstützen das Ereignis nicht. Prüfe die Unterstützung mit 'onscrollsnapchanging' in window und sieh als Fallback IntersectionObserver oder das Ereignis scrollend vor.
Am window kommt das Ereignis nur an, wenn das Dokument selbst einrastet, also scroll-snap-type auf <html> gesetzt ist. Für eigene Scrollcontainer registrierst du den Listener direkt am jeweiligen Element.
Das Ziel ist nur eine Vorhersage. Wenn der Nutzer die Richtung wechselt, kann das Ereignis mehrmals feuern, und das tatsächliche Ziel kann anders ausfallen. Endgültige Aktionen wie Tracking oder Navigation gehören in scrollsnapchange.
Halte den Handler schlank: Aufwendige Änderungen am DOM während der Geste können das Scrollen ruckeln lassen.
Wird eine Snap-Achse nicht verwendet, ist die zugehörige Eigenschaft (snapTargetInline bzw. snapTargetBlock) null. Prüfe den Wert deshalb immer vor dem Zugriff.

Siehe auch

Window: scrollsnapchange Element: scrollsnapchanging SnapEvent IntersectionObserver EventTarget.addEventListener() IdleDetector: change