HTMLImageElement.decoding — Eigenschaft · JavaScript-Referenz

Signatur

HTMLImageElement.decoding

Beschreibung

Die Eigenschaft decoding eines HTMLImageElement spiegelt das gleichnamige HTML-Attribut wider. Sie ist ein Hinweis an den Browser, wie das Dekodieren der Bilddaten (also das Umwandeln von JPEG, PNG, WebP usw. in darstellbare Pixel) zeitlich im Verhältnis zum restlichen Seiteninhalt erfolgen soll.

Mögliche Werte sind:

"sync" – das Bild wird synchron dekodiert und zusammen mit dem übrigen Inhalt atomar dargestellt.
"async" – das Bild wird asynchron dekodiert; anderer Inhalt darf schon vorher gerendert werden, das Bild erscheint ggf. einen Moment später.
"auto" – Standard; der Browser entscheidet selbst.

Nützlich ist "async" vor allem bei großen Bildern oder vielen Bildern, damit das Dekodieren den Hauptthread bzw. das Rendering des übrigen Inhalts nicht blockiert. "sync" eignet sich, wenn ein Bild zwingend gemeinsam mit umgebendem Inhalt erscheinen soll (z. B. beim Austausch eines Platzhalters ohne Flackern).

Weil es sich nur um einen Hinweis handelt, kann der Browser ihn ignorieren. Für eine verlässliche Kontrolle, wann ein Bild fertig dekodiert ist, verwendet man stattdessen HTMLImageElement.prototype.decode(), das ein Promise zurückgibt.

Rückgabewert

Typ

"sync" | "async" | "auto"

Beschreibung

Der aktuelle Dekodier-Hinweis als String. Ungültige oder fehlende Attributwerte werden als "auto" gelesen. Beim Setzen wird das HTML-Attribut decoding aktualisiert.

Beispiele

Großes Bild asynchron dekodieren lassen

const img = new Image();
img.decoding = 'async';
img.src = '/bilder/panorama-8k.jpg';
img.alt = 'Bergpanorama';
document.querySelector('#galerie').append(img);

console.log(img.decoding);
console.log(img.getAttribute('decoding'));

async async

Standardwert und ungültige Werte auslesen

const img = document.createElement('img');
console.log(img.decoding); // kein Attribut gesetzt

img.setAttribute('decoding', 'schnell'); // ungültiger Wert
console.log(img.decoding);

img.decoding = 'SYNC'; // Groß-/Kleinschreibung egal
console.log(img.decoding);

auto auto sync

Alle Bilder unterhalb des sichtbaren Bereichs auf async setzen

const bilder = document.querySelectorAll('img:not([decoding])');

for (const img of bilder) {
  const { top } = img.getBoundingClientRect();
  // Bilder außerhalb des Viewports blockieren das erste Rendering nicht
  img.decoding = top > window.innerHeight ? 'async' : 'auto';
}

console.log(`${bilder.length} Bilder angepasst`);

z. B. 12 Bilder angepasst

Kombination mit decode() für flackerfreien Austausch

const tauscheBild = async (platzhalter, url) => {
  const img = new Image();
  img.decoding = 'async';
  img.src = url;
  try {
    await img.decode(); // wartet, bis Pixel bereitstehen
    platzhalter.replaceWith(img);
  } catch (err) {
    console.error('Bild konnte nicht dekodiert werden:', err);
  }
};

tauscheBild(document.querySelector('.platzhalter'), '/bilder/produkt.webp');

// Wichtig · Fallstricke

Nur ein Hinweis: Browser dürfen den Wert ignorieren. Wer sicher wissen muss, wann ein Bild darstellbar ist, nutzt img.decode().
Nicht mit loading verwechseln: loading="lazy" steuert, wann ein Bild geladen wird; decoding steuert nur das Dekodieren bereits geladener Daten.
"sync" kann bei großen Bildern das Rendering spürbar verzögern und sollte sparsam eingesetzt werden.
Ungültige Werte führen nicht zu einem Fehler, sondern werden als "auto" interpretiert (reflektiertes Aufzählungsattribut, Groß-/Kleinschreibung wird ignoriert).
Die Wirkung ist browserabhängig: Chrome dekodiert Bilder ohnehin häufig außerhalb des Hauptthreads, sodass der Unterschied gering sein kann. Das Attribut existiert auch für SVG-<image>-Elemente (SVGImageElement.decoding).

Siehe auch

HTMLImageElement.attributionSrc HTMLImageElement.loading HTMLImageElement.align HTMLImageElement.border HTMLImageElement.height