DOMRectReadOnly.top — Eigenschaft · JavaScript-Referenz

Signatur

get DOMRectReadOnly.top

Beschreibung

Die schreibgeschützte Eigenschaft top der Schnittstelle DOMRectReadOnly gibt die y-Koordinate der oberen Kante eines Rechtecks zurück. Berechnet wird sie als Math.min(y, y + height). Bei positiver Höhe entspricht top also genau y. Bei negativer Höhe ist top dagegen der Wert y + height.

In der Praxis lesen Sie top meist aus dem Ergebnis von Element.getBoundingClientRect() aus (ein DOMRect, das von DOMRectReadOnly erbt). Weitere Quellen sind IntersectionObserverEntry.boundingClientRect und ResizeObserverEntry.contentRect. Der Wert wird in CSS-Pixeln angegeben und bezieht sich auf den Bezugsrahmen der jeweiligen API. Bei getBoundingClientRect() ist das der Viewport und nicht das Dokument.

Typische Anwendungen sind die Sichtbarkeitsprüfung von Elementen, die Positionierung von Tooltips und Popovers, das Umrechnen in Dokumentkoordinaten (mit window.scrollY) und das Auslösen von „Sticky“-Effekten beim Scrollen.

Rückgabewert

Typ

number

Beschreibung

Die obere Kante des Rechtecks in CSS-Pixeln (Gleitkommazahl), berechnet als Math.min(y, y + height). Der Wert kann negativ sein, etwa wenn ein Element oberhalb des sichtbaren Bereichs liegt.

Beispiele

Obere Kante eines Elements im Viewport ermitteln

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

console.log(`Abstand zum oberen Viewport-Rand: ${rect.top}px`);

// In Dokumentkoordinaten umrechnen (unabhängig vom Scrollstand)
const docTop = rect.top + window.scrollY;
console.log(`Position im Dokument: ${docTop}px`);

Abstand zum oberen Viewport-Rand: 0px Position im Dokument: 0px

Unterschied zwischen top und y bei negativer Höhe

const rect = new DOMRectReadOnly(10, 100, 50, -40);

console.log(rect.y);      // Ursprung
console.log(rect.top);    // Math.min(100, 100 + -40)
console.log(rect.bottom); // Math.max(100, 60)

100 60 100

Tooltip oberhalb eines Buttons positionieren

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

button.addEventListener('mouseenter', () => {
  const { top, left, width } = button.getBoundingClientRect();
  tooltip.style.position = 'fixed';
  tooltip.style.left = `${left + width / 2}px`;
  // Tooltip 8px oberhalb des Buttons, bei Platzmangel darunter
  const tipHeight = tooltip.offsetHeight;
  const y = top - tipHeight - 8;
  tooltip.style.top = `${y < 0 ? top + button.offsetHeight + 8 : y}px`;
  tooltip.hidden = false;
});

Prüfen, ob ein Element den oberen Viewport-Rand passiert hat

const section = document.querySelector('#kapitel-2');

const onScroll = () => {
  const { top } = section.getBoundingClientRect();
  document.body.classList.toggle('kapitel-2-aktiv', top <= 0);
};

window.addEventListener('scroll', onScroll, { passive: true });
onScroll();

// Wichtig · Fallstricke

top ist nicht immer gleich y: Bei negativer Höhe unterscheiden sich die beiden Werte. Wenn Sie die obere Kante brauchen, lesen Sie top. Wenn Sie den Ursprung des Rechtecks brauchen, lesen Sie y.
Viewport-relativ: Bei getBoundingClientRect() hängt top vom aktuellen Scrollstand ab. Für Dokumentkoordinaten addieren Sie window.scrollY.
Schreibgeschützt: Eine Zuweisung an top wird im nicht-strikten Modus stillschweigend ignoriert und löst im Strict Mode einen TypeError aus. Das gilt auch bei einem veränderbaren DOMRect. Um das Rechteck zu verändern, setzen Sie y bzw. height.
Transformationen: CSS-transform wird berücksichtigt. top beschreibt dann die obere Kante des umschließenden Rechtecks und nicht die untransformierte Box.
Performance: Wenn Sie getBoundingClientRect() in Scroll-Handlern aufrufen, kann das ein erzwungenes Layout (Reflow) auslösen. Für Sichtbarkeitsprüfungen ist IntersectionObserver meist die bessere Wahl.
Kompatibilität: Wird von allen modernen Browsern unterstützt. Ältere Versionen des Internet Explorers lieferten ein ClientRect-Objekt ohne x/y, top war dort aber schon vorhanden.

Siehe auch

DOMRectReadOnly DOMRectReadOnly.bottom DOMRectReadOnly.left DOMRectReadOnly.y DOMRectReadOnly.height Element.getBoundingClientRect()