Signatur
Beschreibung
Element.clientTop liefert den Abstand zwischen der äußeren Oberkante eines Elements (Border-Box) und der Oberkante seines Innenbereichs (Padding-Box). In der Praxis entspricht das der Breite des oberen Rahmens, also dem berechneten Wert von border-top-width. Außenabstand (margin) und Innenabstand (padding) zählen nicht dazu.
Die Eigenschaft ist schreibgeschützt und gibt immer eine ganze Zahl zurück. Sie gehört zu den Layout-Eigenschaften clientTop, clientLeft, clientWidth und clientHeight. Hilfreich ist sie vor allem beim Umrechnen von Koordinaten: Ziehst du von der Position aus getBoundingClientRect() noch clientTop ab, kennst du die Position relativ zum Innenbereich des Elements, zum Beispiel für Zeichenflächen, Ziehen-und-Ablegen oder eigene Scrollbalken.
Bei Elementen ohne CSS-Layout-Box ist der Wert 0. Das gilt etwa für Inline-Elemente (display: inline) oder Elemente mit display: none. Anders als bei clientLeft kommt bei clientTop keine Scrollbalkenbreite dazu, weil Browser horizontale Scrollbalken nicht oben am Element darstellen.
Rückgabewert
display: inline oder display: none), ist der Wert 0.Beispiele
Oberen Rand eines Elements auslesen
const box = document.createElement('div');
box.style.cssText = 'border-top: 6px solid navy; border-bottom: 2px solid gray; margin-top: 20px; padding-top: 10px;';
document.body.append(box);
// Nur der obere Rand zählt – margin und padding nicht
console.log(box.clientTop);Mausposition relativ zum Innenbereich berechnen
const canvasWrapper = document.querySelector('#zeichenflaeche');
canvasWrapper.addEventListener('pointerdown', (event) => {
const rect = canvasWrapper.getBoundingClientRect();
// Rahmen abziehen, damit (0|0) an der Innenkante liegt
const x = event.clientX - rect.left - canvasWrapper.clientLeft;
const y = event.clientY - rect.top - canvasWrapper.clientTop;
console.log(`Klick bei x=${Math.round(x)}, y=${Math.round(y)}`);
});Inline-Elemente liefern immer 0
const span = document.createElement('span');
span.textContent = 'Hinweis';
span.style.border = '4px solid red';
document.body.append(span);
console.log(span.clientTop); // Inline: keine Layout-Box
span.style.display = 'inline-block';
console.log(span.clientTop);Genauen Wert mit getComputedStyle vergleichen
const el = document.querySelector('.karte');
const gerundet = el.clientTop;
const exakt = parseFloat(getComputedStyle(el).borderTopWidth);
console.log({ gerundet, exakt });// Wichtig · Fallstricke
- Ganzzahlig: Der Wert ist immer eine ganze Zahl. Bei Rahmen mit Nachkommastellen (z. B.
1.5px,0.1em) oder beitransform: scale()ist er deshalb ungenau. Den genauen Wert bekommst du mitparseFloat(getComputedStyle(el).borderTopWidth). - Transformationen werden ignoriert:
clientTopbeschreibt das Layout vor CSS-Transformationen.getBoundingClientRect()berücksichtigt Transformationen dagegen. Wenn du beide kombinierst, können skalierte Elemente falsche Koordinaten ergeben. - Performance: Wenn du
clientTopliest, muss der Browser das Layout sofort neu berechnen (synchrones Reflow). Wechselst du in Schleifen oder Animationen ständig zwischen Lesen und Schreiben von Stilen, kann das zu Layout-Thrashing führen. Lies deshalb zuerst alle Werte und schreib danach. - 0 statt Fehler: Bei
display: none, Inline-Elementen und Elementen, die nicht im Dokument hängen, kommt0zurück. Es gibt keine Fehlermeldung, daher fällt das leicht nicht auf. - Schreibgeschützt: Eine Zuweisung wie
el.clientTop = 5wird ohne Fehlermeldung ignoriert. - Kompatibilität: Wird seit vielen Jahren von allen gängigen Browsern unterstützt und ist im CSSOM View Module spezifiziert.