DOMRect.width — Eigenschaft · JavaScript-Referenz

Signatur

DOMRect.width

Beschreibung

Die Eigenschaft width eines DOMRect steht für die horizontale Ausdehnung des Rechtecks in CSS-Pixeln. Anders als bei DOMRectReadOnly ist width bei DOMRect les- und schreibbar. Ändert man den Wert, verschieben sich die abgeleiteten Eigenschaften right bzw. left entsprechend. x bleibt dabei unverändert.

Am häufigsten begegnet man width beim Rückgabewert von Element.getBoundingClientRect(). Dort gibt der Wert die tatsächlich gerenderte Breite eines Elements an: mit Innenabstand (padding) und Rahmen (border) und nach Anwendung von CSS-Transformationen wie scale(). Damit eignet sich die Eigenschaft gut für Positionierungslogik, zum Beispiel für Tooltips, Popover, Drag-and-drop oder Kollisionsprüfungen.

Weil ein DOMRect durch Ursprung (x, y) und Größe (width, height) beschrieben wird, darf width negativ sein. Das Rechteck erstreckt sich dann von x aus nach links. Die Eigenschaften left und right geben dagegen immer die kleinere bzw. größere horizontale Koordinate zurück.

Parameter

Name	Typ	Default	Beschreibung
$value	number		Nur beim Setzen: neue Breite in CSS-Pixeln. Wird in eine Gleitkommazahl (`unrestricted double`) umgewandelt. Auch negative Werte, `NaN` und `Infinity` sind erlaubt.

Rückgabewert

Typ

number

Beschreibung

Die Breite des Rechtecks als Gleitkommazahl in CSS-Pixeln. Nachkommastellen sind möglich, der Wert kann auch negativ sein.

Beispiele

Gerenderte Breite eines Elements auslesen

const box = document.createElement('div');
box.style.cssText = 'width:200px;padding:10px;border:5px solid;box-sizing:content-box;';
document.body.append(box);

const rect = box.getBoundingClientRect();
// 200 Inhalt + 2×10 Innenabstand + 2×5 Rahmen
console.log(rect.width);

230

Transformationen werden berücksichtigt

const el = document.createElement('div');
el.style.cssText = 'width:100px;height:50px;transform:scale(1.5);';
document.body.append(el);

console.log(el.offsetWidth);                  // Layoutbreite ohne Transformation
console.log(el.getBoundingClientRect().width); // gerenderte Breite

100 150

width setzen und negative Werte

const rect = new DOMRect(10, 20, 100, 50);
console.log(rect.width, rect.left, rect.right);

rect.width = 40;
console.log(rect.width, rect.right);

// Negative Breite: Das Rechteck erstreckt sich von x aus nach links
rect.width = -30;
console.log(rect.width, rect.left, rect.right);

100 10 110 40 50 -30 -20 10

Praxis: Tooltip über einem Button zentrieren

const positionTooltip = (anchor, tooltip) => {
  const a = anchor.getBoundingClientRect();
  const t = tooltip.getBoundingClientRect();
  const left = a.left + (a.width - t.width) / 2 + window.scrollX;
  const top = a.top - t.height - 8 + window.scrollY;
  Object.assign(tooltip.style, {
    position: 'absolute',
    left: `${Math.max(0, left)}px`,
    top: `${top}px`
  });
};

const btn = document.querySelector('button');
const tip = document.querySelector('.tooltip');
if (btn && tip) positionTooltip(btn, tip);

// Wichtig · Fallstricke

Nachkommastellen: getBoundingClientRect().width liefert meist krumme Werte wie 123.4375. offsetWidth und clientWidth sind dagegen auf ganze Zahlen gerundet. Bei Vergleichen deshalb nicht auf exakte Gleichheit prüfen.
Andere Maße als offsetWidth: width berücksichtigt CSS-Transformationen. offsetWidth gibt dagegen die untransformierte Layoutbreite zurück. Die Breite der Scrollleiste ist in beiden enthalten.
Nicht gerenderte Elemente: Bei display: none oder Elementen, die nicht im Dokument hängen, ist width gleich 0.
Performance: Wer getBoundingClientRect() aufruft, kann ein synchrones Layout erzwingen (Layout Thrashing). Lese- und Schreibzugriffe auf das DOM daher bündeln. Für wiederholte Größenmessungen besser ResizeObserver verwenden.
Nur Momentaufnahme: Ein von getBoundingClientRect() zurückgegebenes Objekt wird nicht automatisch aktualisiert. Wenn Sie width ändern, ändert sich nur das Objekt, nicht das Element.
Schreibschutz: Bei DOMRectReadOnly (z. B. ResizeObserverEntry.contentRect) ist width nur lesbar. Zuweisungen werden ignoriert, im Strict Mode lösen sie einen TypeError aus.
Kompatibilität: Wird in allen modernen Browsern unterstützt. Ältere Versionen von Internet Explorer lieferten stattdessen ein ClientRect-Objekt, teils ohne width/height.

Siehe auch

DOMRect DOMRect.height DOMRect.x DOMRectReadOnly.right Element.getBoundingClientRect() HTMLElement.offsetWidth ResizeObserver