Signatur
Beschreibung
Die Eigenschaft width von HTMLImageElement gibt als ganze Zahl an, wie breit das Bild in CSS-Pixeln dargestellt wird, wenn es auf einem visuellen Medium wie einem Bildschirm oder Drucker gezeichnet wird. Beim Setzen wird das HTML-Attribut width geschrieben. Beim Lesen erhält man die tatsächlich gerenderte Breite, falls das Bild dargestellt wird, also inklusive CSS-Einflüssen wie width: 50% oder max-width, aber ohne Rahmen und Innenabstand.
Wird das Bild nicht gerendert (z. B. bei display: none oder wenn das Element nicht im Dokument hängt), liefert width den Wert des Attributs. Fehlt das Attribut, kommt die natürliche Breite (naturalWidth) zurück, sofern das Bild schon geladen ist, sonst 0.
Gebraucht wird die Eigenschaft vor allem in drei Fällen: um vorab Platz für ein Bild zu reservieren und so Layout-Sprünge (CLS) zu vermeiden, um Bilder per Skript zu skalieren, und um die tatsächlich angezeigte Größe für Canvas-Zeichnungen oder Berechnungen im Layout abzufragen. Die Originalgröße der Bilddatei liefert dagegen naturalWidth.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $value | number | Nur beim Setzen: eine nicht-negative ganze Zahl in CSS-Pixeln. Wird in das Attribut width geschrieben. Nachkommastellen werden abgeschnitten, negative Werte ignoriert (das Attribut wird dann auf 0 gesetzt). |
Rückgabewert
naturalWidth oder 0.Beispiele
Bild dynamisch erzeugen und Platz reservieren
const img = new Image();
// Maße vor dem Laden setzen, so springt das Layout nicht
img.width = 320;
img.height = 180;
img.alt = 'Vorschau';
img.src = '/bilder/vorschau.jpg';
document.body.append(img);
console.log(img.getAttribute('width'));Gerenderte Breite und natürliche Breite vergleichen
const img = document.querySelector('#hero');
img.addEventListener('load', () => {
console.log(`Angezeigt: ${img.width}px`);
console.log(`Original: ${img.naturalWidth}px`);
if (img.naturalWidth > img.width * 2) {
console.warn('Bild ist viel zu groß für die Anzeigefläche');
}
});Bild proportional auf Maximalbreite skalieren
const fitToWidth = async (img, maxWidth) => {
await img.decode(); // warten, bis die natürlichen Maße bekannt sind
if (img.naturalWidth > maxWidth) {
const ratio = maxWidth / img.naturalWidth;
img.width = maxWidth;
img.height = Math.round(img.naturalHeight * ratio);
}
return { width: img.width, height: img.height };
};
const img = new Image();
img.src = '/bilder/foto-1600x900.jpg';
fitToWidth(img, 800).then(console.log);Verhalten bei nicht gerendertem Bild
const img = document.createElement('img');
console.log(img.width); // weder Attribut noch geladenes Bild
img.setAttribute('width', '150');
console.log(img.width); // nicht im DOM, also Attributwert// Wichtig · Fallstricke
- Ohne Einheit:
widthist immer eine ganze Zahl in CSS-Pixeln. Prozentangaben wie"50%"funktionieren hier nicht. Dafür gibt esimg.style.width. - CSS hat Vorrang: Setzt ein Stylesheet eine Breite, bestimmt es die Darstellung. Das Attribut bleibt zwar gesetzt, beim Lesen erhält man aber die von CSS bestimmte gerenderte Breite.
- Zeitpunkt beachten: Vor dem
load-Ereignis bzw. vordecode()ist die Breite oft0, sofern kein Attribut gesetzt ist. - Nicht mit
naturalWidthverwechseln:naturalWidthist die tatsächliche Pixelbreite der Datei, unabhängig von der Darstellung. Die Dichte-Deskriptoren insrcset(z. B.2x) beeinflussen die natürliche Größe. - Layout-Stabilität: Moderne Browser berechnen aus den Attributen
widthundheightein Seitenverhältnis (aspect-ratio), um vor dem Laden Platz zu reservieren. Deshalb sollte man beide Attribute immer angeben. - Performance: Wenn ein gerendertes Bild gelesen wird, kann das eine synchrone Layout-Berechnung (Reflow) erzwingen. Lesen und Schreiben in Schleifen sollte man nicht abwechseln.
- Die Eigenschaft wird von allen Browsern unterstützt.