DOMRect.y — Eigenschaft · JavaScript-Referenz

Signatur

DOMRect.y

Beschreibung

Die Eigenschaft y gibt die vertikale Koordinate des Ursprungs eines Rechtecks in CSS-Pixeln an. Stammt das Rechteck aus Element.getBoundingClientRect(), ist y der Abstand zwischen der oberen Kante des Viewports und der oberen Rahmenkante des Elements. Scrollt die Seite, ändert sich dieser Wert entsprechend. Liegt das Element oberhalb des sichtbaren Bereichs, ist er negativ.

Bei DOMRect ist y anders als bei DOMRectReadOnly schreibbar. Wenn du y setzt, verschiebst du das Rechteck vertikal, die Höhe bleibt gleich. Die abgeleiteten Eigenschaften top und bottom werden automatisch neu berechnet.

Wichtig ist der Unterschied zu top: top ist immer Math.min(y, y + height). Bei positiver Höhe sind beide Werte gleich. Ein manuell erzeugtes DOMRect kann aber eine negative Höhe haben, und dann liegt der Ursprung y an der unteren Kante.

Typische Einsatzfälle sind Positionsberechnungen für Tooltips und Popover, die Prüfung, ob ein Element sichtbar ist, Sticky-Logik und die Umrechnung in Dokumentkoordinaten über y + window.scrollY.

Parameter

Name	Typ	Default	Beschreibung
$value	number	0	Nur beim Setzen: neue y-Koordinate des Ursprungs in CSS-Pixeln (Gleitkommazahl, auch negativ möglich).

Rückgabewert

Typ

number

Beschreibung

Die y-Koordinate des Rechteck-Ursprungs als Gleitkommazahl (Double) in CSS-Pixeln. Nachkommastellen sind möglich, z. B. 123.5.

Beispiele

Abstand eines Elements zur oberen Viewport-Kante

const header = document.querySelector('h1');
const rect = header.getBoundingClientRect();

console.log(`Abstand zum Viewport oben: ${rect.y}px`);
// Umrechnung in Dokumentkoordinaten (unabhängig vom Scrollen)
console.log(`Position im Dokument: ${rect.y + window.scrollY}px`);

Abstand zum Viewport oben: 21.44px Position im Dokument: 21.44px

DOMRect erzeugen und vertikal verschieben

const rect = new DOMRect(10, 20, 100, 50);
console.log(rect.y, rect.top, rect.bottom);

// y ist bei DOMRect schreibbar – top/bottom passen sich an
rect.y = 80;
console.log(rect.y, rect.top, rect.bottom);

20 20 70 80 80 130

Unterschied zwischen y und top bei negativer Höhe

const rect = new DOMRect(0, 100, 50, -40);
console.log(`y: ${rect.y}`);
console.log(`top: ${rect.top}`);
console.log(`bottom: ${rect.bottom}`);

y: 100 top: 60 bottom: 100

Tooltip unter einem Button positionieren

const button = document.querySelector('#hilfe');
const tooltip = document.querySelector('#tooltip');

button.addEventListener('mouseenter', () => {
  const { x, y, height } = button.getBoundingClientRect();
  // position: fixed → Viewport-Koordinaten direkt verwendbar
  tooltip.style.position = 'fixed';
  tooltip.style.left = `${x}px`;
  tooltip.style.top = `${y + height + 8}px`;
  tooltip.hidden = false;
});

// Wichtig · Fallstricke

y ist nicht immer gleich top: Bei negativer Höhe unterscheiden sich die Werte. Für die sichtbare Oberkante ist top die sicherere Wahl.
Momentaufnahme: Das Rechteck aus getBoundingClientRect() wird nicht aktualisiert. Nach dem Scrollen, einer Größenänderung oder einer Layout-Änderung musst du es neu abfragen.
Viewport- statt Dokumentkoordinaten: Für absolute Positionierung im Dokument musst du window.scrollY addieren.
Performance: getBoundingClientRect() erzwingt eine synchrone Layout-Berechnung. Wechseln sich Lese- und Schreibzugriffe in Schleifen ab, kann das Layout-Thrashing auslösen. Für Sichtbarkeitsprüfungen ist IntersectionObserver oft besser.
Transformationen: CSS-transform wirkt sich auf den Wert aus. Es wird die umschließende Box nach der Transformation gemessen.
Schreibbarkeit: Bei DOMRectReadOnly ist y schreibgeschützt. Zuweisungen werden dort stillschweigend ignoriert, im Strict Mode lösen sie einen TypeError aus. Ältere Browser (z. B. Internet Explorer) kennen x/y bei ClientRect gar nicht, nur left/top.

Siehe auch

DOMRect.x DOMRect.height DOMRectReadOnly.top DOMRectReadOnly.bottom Element.getBoundingClientRect() DOMRectReadOnly IntersectionObserver