Signatur
Beschreibung
Die schreibgeschützte Eigenschaft y des HTMLImageElement liefert die vertikale Position der oberen Rahmenkante (border edge) des ersten Layout-Kastens eines Bildes. Der Wert wird relativ zum Ursprung des initialen umschließenden Blocks gemessen, also zur oberen linken Ecke des Dokuments – nicht zum sichtbaren Ausschnitt (Viewport). Scrollt die Seite, bleibt y deshalb gleich.
Die Eigenschaft ist praktisch, wenn man schnell die absolute Dokumentposition eines Bildes braucht, etwa um mit window.scrollTo() dorthin zu springen, um Bildpositionen für eigene Overlays oder Tooltips zu berechnen oder um festzustellen, in welcher Reihenfolge Bilder auf der Seite erscheinen.
Wichtig: CSS-Transformationen (transform) werden bei der Berechnung ignoriert, und der Wert ist eine Ganzzahl (Typ long). Hat das Element keinen Layout-Kasten – etwa bei display: none oder wenn es nicht im Dokument hängt –, liefert y den Wert 0. Für präzise, transformationsbewusste Werte mit Nachkommastellen ist getBoundingClientRect() die bessere Wahl.
Rückgabewert
0, wenn kein Layout-Kasten existiert.Beispiele
Position eines Bildes auslesen
// HTML: <img id="logo" src="logo.png" alt="Logo">
const logo = document.getElementById('logo');
// Erst nach dem Laden ist die Bildhöhe und damit das Layout stabil
logo.addEventListener('load', () => {
console.log(`Logo liegt bei x=${logo.x}, y=${logo.y}`);
});Zu einem bestimmten Bild scrollen
const scrollToImage = (img, offset = 20) => {
// y ist dokumentbezogen – passt direkt zu window.scrollTo
window.scrollTo({ top: img.y - offset, behavior: 'smooth' });
};
const galleryImage = document.querySelector('.gallery img:nth-child(5)');
if (galleryImage) scrollToImage(galleryImage);Vergleich mit getBoundingClientRect()
const img = document.querySelector('img');
// getBoundingClientRect() ist viewport-bezogen, daher Scrollposition addieren
const rectTop = img.getBoundingClientRect().top + window.scrollY;
console.log('img.y:', img.y);
console.log('Rect + scrollY:', rectTop);
// Ohne transform stimmen beide (bis auf Rundung) übereinBilder nach vertikaler Position sortieren
const images = [...document.images]
.filter((img) => img.y > 0) // unsichtbare Bilder (y = 0) aussortieren
.sort((a, b) => a.y - b.y);
images.forEach((img) => console.log(img.y, img.alt));// Wichtig · Fallstricke
- Schreibgeschützt: Eine Zuweisung wie
img.y = 100hat keine Wirkung (im Strict Mode kein Fehler, da nur ein Getter existiert). Zum Verschieben CSS (top,transform,margin) verwenden. - Transformationen werden ignoriert: Ein per
transform: translateY(...)verschobenes Bild meldet weiterhin die ursprüngliche Position.getBoundingClientRect()berücksichtigt Transformationen. - Ganzzahl: Der Wert wird gerundet; für subpixelgenaue Berechnungen ungeeignet.
- Kein Layout = 0: Bei
display: none, nicht eingehängten Elementen (new Image()ohneappend) istygleich0– nicht mit „ganz oben“ verwechseln. - Layout-Neuberechnung: Das Auslesen erzwingt ggf. ein synchrones Layout (Reflow). In Schleifen mit gleichzeitigen DOM-Änderungen Lese- und Schreibzugriffe bündeln.
- Timing: Vor dem
load-Ereignis kann sich die Position noch ändern, wenn Bilder ohne festewidth/heightnachträglich Platz einnehmen. - Kompatibilität: Wird von allen aktuellen Browsern unterstützt; die Eigenschaft stammt ursprünglich aus Netscape und wurde im CSSOM View Module standardisiert. Sie existiert nur auf
HTMLImageElement, nicht auf beliebigen Elementen.