ResizeObserver.observe() — Methode · JavaScript-Referenz

Signatur

ResizeObserver.prototype.observe(target, options)

Beschreibung

Mit observe() registrierst du ein Element bei einem bestehenden ResizeObserver. Sobald sich die Größe des Elements ändert, ruft der Browser den Callback des Observers mit einem Array von ResizeObserverEntry-Objekten auf. Ein Observer kann beliebig viele Elemente gleichzeitig beobachten. Die Größen werden gebündelt gemeldet, und zwar nach dem Layout und vor dem Zeichnen.

Anders als das resize-Event von window reagiert ResizeObserver auf Größenänderungen einzelner Elemente, egal was sie auslöst: Viewport-Änderungen, neuer Inhalt, CSS-Animationen oder verschobene Flex-/Grid-Layouts. Das macht die Methode zum Standardwerkzeug für komponentenbasierte Responsivität, Canvas-Skalierung, virtuelle Listen oder Diagramme, die sich an ihren Container anpassen.

Über das Optionsobjekt legst du mit box fest, welches Box-Modell gemessen wird: content-box (Standard), border-box oder device-pixel-content-box. Letzteres liefert die Größe in echten Gerätepixeln und eignet sich für pixelgenaues Canvas-Rendering.

Direkt nach dem Aufruf von observe() wird der Callback einmal mit der aktuellen Größe ausgelöst, sofern das Element gerendert ist und seine Größe nicht 0×0 beträgt. Du brauchst also keine separate Initialmessung.

Parameter

Name	Typ	Default	Beschreibung
$target Pflicht	Element \| SVGElement		Das Element, dessen Größe beobachtet werden soll.
$options	{ box?: 'content-box' \| 'border-box' \| 'device-pixel-content-box' }	{ box: 'content-box' }	Optionales Objekt. `box` legt fest, welches Box-Modell für die Änderungserkennung gilt. Nur wenn sich diese Box ändert, wird der Callback ausgelöst.

Rückgabewert

Typ

void

Beschreibung

Gibt undefined zurück. Die Messwerte kommen asynchron im Callback des Observers an.

Beispiele

Container-Breite beobachten und Layout-Klasse setzen

const card = document.querySelector('.card');

const ro = new ResizeObserver((entries) => {
  for (const entry of entries) {
    const width = entry.contentBoxSize[0].inlineSize;
    entry.target.classList.toggle('card--compact', width < 400);
    console.log(`Breite: ${Math.round(width)}px`);
  }
});

ro.observe(card);

Breite: 620px

Canvas pixelgenau skalieren mit device-pixel-content-box

const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');

const ro = new ResizeObserver(([entry]) => {
  const size = entry.devicePixelContentBoxSize?.[0];
  const w = size ? size.inlineSize : Math.round(entry.contentRect.width * devicePixelRatio);
  const h = size ? size.blockSize : Math.round(entry.contentRect.height * devicePixelRatio);
  canvas.width = w;
  canvas.height = h;
  ctx.fillStyle = 'teal';
  ctx.fillRect(0, 0, w, h);
  console.log(`Canvas: ${w}×${h} Gerätepixel`);
});

try {
  ro.observe(canvas, { box: 'device-pixel-content-box' });
} catch {
  // Fallback, z. B. für ältere Safari-Versionen
  ro.observe(canvas);
}

Canvas: 1600×900 Gerätepixel

Mehrere Elemente beobachten und später aufräumen

const panels = document.querySelectorAll('.panel');

const ro = new ResizeObserver((entries) => {
  entries.forEach(({ target, borderBoxSize }) => {
    const { inlineSize, blockSize } = borderBoxSize[0];
    target.dataset.size = `${Math.round(inlineSize)}x${Math.round(blockSize)}`;
  });
});

panels.forEach((panel) => ro.observe(panel, { box: 'border-box' }));

// Einzelnes Element abmelden
ro.unobserve(panels[0]);

// Beim Entfernen der Komponente alles beenden
window.addEventListener('pagehide', () => ro.disconnect());

// Wichtig · Fallstricke

Endlosschleifen: Wenn du im Callback die Größe des beobachteten Elements selbst änderst, kann das erneute Benachrichtigungen auslösen. Der Browser bricht solche Kaskaden ab und meldet ResizeObserver loop completed with undelivered notifications als Fehler-Event auf window. Ändere Größen deshalb vorsichtig oder verschiebe sie per requestAnimationFrame.
Wird dasselbe Element erneut mit observe() registriert, wirft das keinen Fehler. Es werden nur die Optionen (box) aktualisiert.
Ist target kein Element, wirft die Methode einen TypeError. Ein unbekannter box-Wert führt ebenfalls zu einem TypeError.
Elemente mit display: none oder außerhalb des DOM melden eine Größe von 0×0. Bei nicht-ersetzten Inline-Elementen ist die Größe immer 0.
Bewegungen oder Transformationen (transform: scale()) lösen keine Benachrichtigung aus, denn gemessen wird nur die Layout-Größe.
Kompatibilität: observe() ist in allen modernen Browsern verfügbar. contentBoxSize und borderBoxSize sind Arrays, in alten Firefox-Versionen waren es Einzelobjekte. device-pixel-content-box unterstützt Safari erst seit Version 17.
Rufe disconnect() oder unobserve() auf, wenn Komponenten entfernt werden. So vermeidest du unnötige Callbacks und hältst keine Referenzen länger als nötig.

Siehe auch

FileSystemObserver.observe() ResizeObserver.unobserve() ResizeObserver.disconnect() PressureObserver.observe() PressureObserver.unobserve()