HTMLImageElement.height — Eigenschaft · JavaScript-Referenz

Signatur

HTMLImageElement.height

Beschreibung

Die Eigenschaft height eines HTMLImageElement gibt die Höhe an, in der das Bild auf einem visuellen Medium wie Bildschirm oder Drucker gezeichnet wird. Der Wert ist eine ganze Zahl in CSS-Pixeln. Beim Lesen erhältst du die tatsächlich gerenderte Höhe, wenn das Bild angezeigt wird. Ist das nicht der Fall, bekommst du den Wert des height-Attributs oder, wenn es fehlt, die natürliche Höhe des Bildes (naturalHeight), sofern diese bekannt ist. Andernfalls ist der Wert 0.

Beim Schreiben setzt die Eigenschaft das HTML-Attribut height. Das entspricht img.setAttribute('height', wert). Hat CSS eine Höhe festgelegt (z. B. height: 50% oder height: auto), gilt beim Rendern die CSS-Regel. Das Attribut dient dann vor allem als Hinweis auf das Seitenverhältnis.

In der Praxis brauchst du height vor allem für zwei Dinge. Erstens solltest du width und height vorab setzen, damit der Browser Platz reserviert und das Layout beim Laden nicht springt (Cumulative Layout Shift). Zweitens kannst du nach dem Laden die gerenderte Größe auslesen, etwa um ein Bild auf ein <canvas> zu zeichnen oder Positionen zu berechnen.

Wenn du die Pixelgröße der Bilddatei selbst brauchst, nimm naturalHeight. Für die gerenderte Größe mit Nachkommastellen, inklusive CSS-Transformationen, eignet sich getBoundingClientRect().

Parameter

Name	Typ	Default	Beschreibung
$wert	number		Nur beim Schreiben: neue Höhe in CSS-Pixeln als ganze Zahl ohne Vorzeichen. Der Wert wird in das Attribut `height` geschrieben. Nachkommastellen werden abgeschnitten.

Rückgabewert

Typ

number

Beschreibung

Ganze Zahl mit der gerenderten Höhe in CSS-Pixeln. Wird das Bild nicht gerendert, ist es der Attributwert oder naturalHeight. Ohne Information ist der Wert 0.

Beispiele

Höhe nach dem Laden auslesen

const img = document.querySelector('#hero');

const logSize = () => {
  console.log(`Gerendert: ${img.width}×${img.height}px`);
  console.log(`Natürlich: ${img.naturalWidth}×${img.naturalHeight}px`);
};

if (img.complete) {
  logSize();
} else {
  img.addEventListener('load', logSize, { once: true });
}

Gerendert: 640×360px Natürlich: 1920×1080px

Platz reservieren gegen Layout-Sprünge

const createImage = (src, w, h, alt) => {
  const img = new Image();
  img.width = w;   // setzt das Attribut width
  img.height = h;  // setzt das Attribut height
  img.alt = alt;
  img.loading = 'lazy';
  img.src = src;
  return img;
};

const img = createImage('/bilder/produkt.jpg', 400, 300, 'Produktfoto');
document.querySelector('.gallery').append(img);
console.log(img.getAttribute('height'));

300

Bild proportional auf eine Zielhöhe skalieren

const scaleToHeight = async (img, targetHeight) => {
  await img.decode(); // wartet, bis das Bild dekodiert ist
  const ratio = img.naturalWidth / img.naturalHeight;
  img.height = targetHeight;
  img.width = Math.round(targetHeight * ratio);
  return { width: img.width, height: img.height };
};

const thumb = document.querySelector('img.thumb');
scaleToHeight(thumb, 120).then(size => console.log(size));

{ width: 213, height: 120 }

Bild in passender Größe auf ein Canvas zeichnen

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

img.addEventListener('load', () => {
  canvas.width = img.width;
  canvas.height = img.height;
  ctx.drawImage(img, 0, 0, img.width, img.height);
  console.log(`Canvas: ${canvas.width}×${canvas.height}`);
}, { once: true });

Canvas: 200×80

// Wichtig · Fallstricke

Vor dem Laden oft 0: Solange das Bild nicht geladen ist und kein height-Attribut hat, liefert height den Wert 0. Lies den Wert erst nach dem load-Ereignis, nach img.decode() oder wenn img.complete wahr ist.
Nicht gerenderte Bilder: Bei display: none oder bei Bildern, die nicht im DOM hängen (new Image()), gibt height den Attributwert oder naturalHeight zurück, nicht eine gerenderte Größe.
CSS hat Vorrang: Legt ein Stylesheet die Höhe fest, schreibt das Setzen von img.height zwar das Attribut, ändert aber die Darstellung nicht. Für eine sichtbare Änderung in diesem Fall img.style.height verwenden.
Nur ganze Zahlen: Werte werden gerundet bzw. abgeschnitten. Prozentangaben wie '50%' sind nicht erlaubt; ungültige Werte werden als 0 gespeichert. Für genaue Maße mit Nachkommastellen getBoundingClientRect().height nutzen.
Keine Geräte-Pixel: Der Wert ist in CSS-Pixeln angegeben. Für scharfe Canvas-Darstellung auf HiDPI-Bildschirmen mit window.devicePixelRatio multiplizieren.
Kompatibilität: Wird von allen Browsern seit jeher unterstützt. Dass moderne Browser aus width/height automatisch aspect-ratio ableiten, um Layout-Sprünge zu vermeiden, gilt erst seit etwa 2020 (Chrome 79, Firefox 71, Safari 14).

Siehe auch

HTMLImageElement.align HTMLImageElement.alt HTMLImageElement.hspace HTMLImageElement.sizes HTMLImageElement.srcset