new SnapEvent() — Methode · JavaScript-Referenz

Signatur

new SnapEvent(type, options)

Beschreibung

Der Konstruktor SnapEvent() erzeugt eine neue Instanz von SnapEvent. Dieses Ereignisobjekt gehört zu CSS Scroll Snap und wird vom Browser bei zwei Ereignissen an Scroll-Containern ausgelöst:

scrollsnapchanging: Wird schon während einer Scroll-Geste ausgelöst, sobald der Browser ein neues Einrastziel (Snap-Ziel) vorsieht.
scrollsnapchange: Wird ausgelöst, wenn der Scrollvorgang beendet ist und tatsächlich an einem neuen Ziel eingerastet wurde.

Über die Eigenschaften snapTargetBlock und snapTargetInline erfährt man, welches Element auf der Block- bzw. Inline-Achse eingerastet ist. Damit lassen sich z. B. Karussells, Bildergalerien oder Seiten-Indikatoren ohne IntersectionObserver oder Scroll-Berechnungen umsetzen.

Den Konstruktor selbst braucht man selten, weil der Browser diese Ereignisse normalerweise erzeugt. Nützlich ist er vor allem für Tests, um Ereignisbehandler mit einem künstlich erzeugten Ereignis aufzurufen, oder um in eigenen Komponenten ein Snap-Verhalten nachzubilden.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, üblicherweise `"scrollsnapchange"` oder `"scrollsnapchanging"`. Groß-/Kleinschreibung wird beachtet.
$options	object	{}	Optionales Objekt, das zusätzlich zu den Feldern von `EventInit` (`bubbles`, `cancelable`, `composed`) folgende Felder erlaubt: `snapTargetBlock` (`Node \| null`, Standard `null`): eingerastetes Element auf der Blockachse (bei horizontaler Schreibrichtung vertikal). `snapTargetInline` (`Node \| null`, Standard `null`): eingerastetes Element auf der Inline-Achse (bei horizontaler Schreibrichtung horizontal).

Rückgabewert

Typ

SnapEvent

Beschreibung

Ein neues SnapEvent-Objekt, das man mit dispatchEvent() an ein Element senden kann. Es hat isTrusted === false.

Beispiele

SnapEvent erzeugen und Eigenschaften auslesen

const slide = document.createElement('section');
slide.id = 'slide-2';

const event = new SnapEvent('scrollsnapchange', {
  snapTargetInline: slide,
  snapTargetBlock: null
});

console.log(event.type);
console.log(event.snapTargetInline.id);
console.log(event.snapTargetBlock);
console.log(event.isTrusted);

scrollsnapchange slide-2 null false

Karussell-Indikator auf echte Snap-Ereignisse reagieren lassen

// HTML: <div class="carousel"> mit <section data-index="…"> als Kindern
// CSS: .carousel { overflow-x: auto; scroll-snap-type: x mandatory; }
//      .carousel > section { scroll-snap-align: center; }
const carousel = document.querySelector('.carousel');
const indicator = document.querySelector('#indicator');

const updateIndicator = (event) => {
  const target = event.snapTargetInline;
  if (target) {
    indicator.textContent = `Folie ${Number(target.dataset.index) + 1}`;
  }
};

// Endgültiges Einrasten
carousel.addEventListener('scrollsnapchange', updateIndicator);

// Vorschau schon während der Geste
carousel.addEventListener('scrollsnapchanging', (event) => {
  carousel.querySelectorAll('section').forEach((s) =>
    s.classList.toggle('pending', s === event.snapTargetInline)
  );
});

Behandler im Test mit synthetischem Ereignis prüfen

const carousel = document.createElement('div');
const slide = document.createElement('section');
slide.dataset.index = '3';
carousel.append(slide);

let aktiverIndex = null;
carousel.addEventListener('scrollsnapchange', (e) => {
  aktiverIndex = Number(e.snapTargetInline?.dataset.index);
});

// Nur ausführen, wenn der Browser die API kennt
if ('SnapEvent' in window) {
  carousel.dispatchEvent(
    new SnapEvent('scrollsnapchange', { snapTargetInline: slide })
  );
  console.log(aktiverIndex);
} else {
  console.log('SnapEvent wird nicht unterstützt');
}

3

// Wichtig · Fallstricke

Browser-Unterstützung: SnapEvent ist experimentell und bisher nur in Chromium-Browsern (Chrome/Edge ab Version 129) verfügbar. Vorher mit 'SnapEvent' in window oder 'onscrollsnapchange' in window prüfen und für andere Browser eine Alternative bereitstellen, z. B. IntersectionObserver oder scrollend.
Die Ereignisse werden nur ausgelöst, wenn der Container tatsächlich Scroll-Snapping nutzt (scroll-snap-type am Container, scroll-snap-align an den Kindern).
snapTargetBlock und snapTargetInline können null sein, wenn auf der jeweiligen Achse kein Einrasten stattfindet. Deshalb immer auf null prüfen, z. B. mit ?..
Wird ein Pseudo-Element als Ziel eingerastet, verweist die Eigenschaft auf das zugehörige Ursprungselement.
Mit dem Konstruktor erzeugte Ereignisse haben isTrusted === false und lösen kein echtes Scrollen aus. Sie rufen nur die registrierten Behandler auf. Ohne bubbles: true steigen sie außerdem nicht im DOM auf.
scrollsnapchanging kann während einer Geste mehrmals ausgelöst werden. Aufwendige Arbeit sollte man deshalb erst bei scrollsnapchange erledigen.

Siehe auch

new Event() new DragEvent() new SyncEvent() new BlobEvent() new InputEvent()