Signatur
Beschreibung
Die schreibgeschützte Eigenschaft borderBoxSize einer ResizeObserverEntry enthält die Größe der Border-Box des beobachteten Elements zu dem Zeitpunkt, an dem der Callback läuft. Die Border-Box umfasst Inhalt, Innenabstand (padding) und Rahmen (border), aber keinen Außenabstand (margin). Das entspricht dem, was ein Element sichtbar einnimmt, und ungefähr den Werten von offsetWidth/offsetHeight.
Der Wert ist ein Array von ResizeObserverSize-Objekten mit den Eigenschaften inlineSize und blockSize. Diese logischen Maße richten sich nach dem Schreibmodus: Bei horizontalem Text (writing-mode: horizontal-tb) ist inlineSize die Breite und blockSize die Höhe, bei vertikalem Text ist es umgekehrt. Mehrere Einträge sind für fragmentierte Elemente vorgesehen (z. B. in mehrspaltigen Layouts). Derzeit liefern Browser aber praktisch immer genau einen Eintrag, deshalb greift man normalerweise mit borderBoxSize[0] zu.
Die Eigenschaft ist immer gefüllt, egal mit welcher box-Option observe() aufgerufen wurde. Die Option entscheidet nur, welche Größenänderung den Callback auslöst. Wenn du auf Änderungen der Border-Box reagieren willst (auch wenn sich nur Rahmen oder Innenabstand ändern), beobachte mit { box: 'border-box' }.
Rückgabewert
ResizeObserverSize-Objekten mit inlineSize und blockSize in CSS-Pixeln. Heute ist es praktisch immer ein einziges Element.Beispiele
Border-Box-Größe einer Karte protokollieren
const card = document.querySelector('.card');
const observer = new ResizeObserver((entries) => {
for (const entry of entries) {
const [size] = entry.borderBoxSize;
console.log(`Breite: ${size.inlineSize}px, Höhe: ${size.blockSize}px`);
}
});
// Callback auch bei Änderungen an padding/border auslösen
observer.observe(card, { box: 'border-box' });Responsives Komponenten-Layout (Container-Breakpoints)
const widget = document.querySelector('#widget');
const ro = new ResizeObserver(([entry]) => {
const width = entry.borderBoxSize?.[0]?.inlineSize
?? entry.contentRect.width; // Fallback für alte Browser
widget.classList.toggle('is-compact', width < 400);
widget.classList.toggle('is-wide', width >= 800);
});
ro.observe(widget, { box: 'border-box' });Border-Box und Content-Box vergleichen
const box = document.querySelector('.box');
box.style.cssText = 'width:200px;padding:20px;border:5px solid;box-sizing:content-box';
new ResizeObserver(([entry]) => {
const border = entry.borderBoxSize[0];
const content = entry.contentBoxSize[0];
console.log('Border-Box:', border.inlineSize);
console.log('Content-Box:', content.inlineSize);
}).observe(box);Logische Maße bei vertikalem Schreibmodus
const el = document.querySelector('.vertical');
el.style.cssText = 'writing-mode:vertical-rl;width:100px;height:300px';
new ResizeObserver(([entry]) => {
const { inlineSize, blockSize } = entry.borderBoxSize[0];
// inlineSize entspricht hier der physischen Höhe
console.log({ inlineSize, blockSize });
}).observe(el);// Wichtig · Fallstricke
- Ältere Implementierungen: Firefox vor Version 92 lieferte hier ein einzelnes
ResizeObserverSize-Objekt statt eines Arrays. Sehr alte Chromium-Versionen (vor 84) kennen die Eigenschaft gar nicht. Für robusten Code:Array.isArray(entry.borderBoxSize) ? entry.borderBoxSize[0] : entry.borderBoxSize, mitcontentRectals letztem Fallback. - Logische statt physische Maße:
inlineSizeist nicht immer die Breite. Beiwriting-mode: vertical-*sind die Achsen vertauscht. - Transformationen: CSS-
transform(z. B.scale()) wirkt sich nicht auf den Wert aus. Für die tatsächlich gerenderte Größe nimmst dugetBoundingClientRect(). - Endlosschleifen: Wenn du im Callback die Größe des beobachteten Elements änderst, kann das neue Resize-Ereignisse auslösen. Der Browser bricht dann mit der Fehlermeldung „ResizeObserver loop completed with undelivered notifications“ ab.
- Die Werte sind Gleitkommazahlen in CSS-Pixeln und nicht auf ganze Pixel gerundet. Für pixelgenaues Canvas-Rendering eignet sich
devicePixelContentBoxSize.