HTMLImageElement.srcset — Eigenschaft · JavaScript-Referenz

Signatur

HTMLImageElement.srcset

Beschreibung

Die Eigenschaft srcset spiegelt das gleichnamige HTML-Attribut eines <img>-Elements wider. Ihr Wert ist ein String mit einem oder mehreren Bildkandidaten, getrennt durch Kommas. Jeder Kandidat besteht aus einer Bild-URL und optional einem Deskriptor: entweder einer Breitenangabe in Pixeln (480w) oder einer Pixeldichte (2x, 1.5x). Fehlt der Deskriptor, gilt 1x.

Anhand dieser Liste wählt der Browser selbst die passende Ressource aus. Kriterien sind die Pixeldichte des Bildschirms (devicePixelRatio), die Layoutbreite aus dem Attribut sizes und unter Umständen auch Netzwerkbedingungen oder der Cache. So bekommen Retina-Displays scharfe Bilder, während Mobilgeräte kleinere Dateien laden und Bandbreite sparen.

Für Breitendeskriptoren (w) sollte immer auch sizes gesetzt sein. Ohne sizes nimmt der Browser 100vw an, also die volle Breite des Viewports. Dichtedeskriptoren (x) eignen sich für Bilder mit fester Darstellungsgröße, etwa Logos oder Icons. Beide Deskriptor-Arten dürfen in einem srcset nicht gemischt werden.

Welches Bild tatsächlich geladen wurde, steht in der schreibgeschützten Eigenschaft currentSrc. Die Eigenschaft src bleibt als Rückfall für Browser ohne srcset-Unterstützung bestehen. Außerdem gilt src als 1x-Kandidat, wenn srcset keinen enthält.

Parameter

Name	Typ	Default	Beschreibung
$value	string	""	Beim Setzen: kommagetrennte Liste im Format `URL [Deskriptor]`, z. B. `"a.jpg 480w, b.jpg 960w"` oder `"logo.png, logo@2x.png 2x"`. Ein leerer String entfernt die Kandidaten praktisch wieder.

Rückgabewert

Typ

string

Beschreibung

Der aktuelle Wert des srcset-Attributs, genau wie im HTML angegeben. URLs werden dabei nicht zu absoluten URLs aufgelöst. Ist das Attribut nicht gesetzt, ist der Wert ein leerer String.

Beispiele

Retina-Logo mit Dichtedeskriptoren

const logo = document.createElement('img');
logo.src = '/img/logo.png'; // Rückfall und 1x-Kandidat
logo.srcset = '/img/logo@2x.png 2x, /img/logo@3x.png 3x';
logo.alt = 'Firmenlogo';
logo.width = 160;
logo.height = 40;
document.querySelector('header').append(logo);

console.log(logo.srcset);

/img/logo@2x.png 2x, /img/logo@3x.png 3x

Responsives Artikelbild mit Breitendeskriptoren und sizes

const img = document.querySelector('#hero');
const widths = [480, 960, 1440, 1920];

img.srcset = widths
  .map((w) => `/bilder/hero-${w}.jpg ${w}w`)
  .join(', ');
// Bild ist auf Mobilgeräten vollbreit, ab 800px höchstens 50vw breit
img.sizes = '(min-width: 800px) 50vw, 100vw';

img.addEventListener('load', () => {
  console.log('Geladen:', img.currentSrc);
}, { once: true });

Geladen: https://example.com/bilder/hero-960.jpg (abhängig von Viewport und Pixeldichte)

srcset auswerten – Kandidaten parsen

const parseSrcset = (srcset) =>
  srcset
    .split(/,\s+/)
    .filter(Boolean)
    .map((entry) => {
      const [url, descriptor = '1x'] = entry.trim().split(/\s+/);
      return { url, descriptor };
    });

const img = new Image();
img.srcset = 'klein.webp 400w, mittel.webp 800w, gross.webp 1600w';
console.table(parseSrcset(img.srcset));

[{url: 'klein.webp', descriptor: '400w'}, {url: 'mittel.webp', descriptor: '800w'}, {url: 'gross.webp', descriptor: '1600w'}]

Lazy Loading: srcset erst bei Sichtbarkeit setzen

const observer = new IntersectionObserver((entries, obs) => {
  for (const { isIntersecting, target } of entries) {
    if (!isIntersecting) continue;
    target.srcset = target.dataset.srcset; // aus data-srcset übernehmen
    target.removeAttribute('data-srcset');
    obs.unobserve(target);
  }
}, { rootMargin: '200px' });

document.querySelectorAll('img[data-srcset]').forEach((img) => observer.observe(img));

// Wichtig · Fallstricke

Die Auswahl trifft der Browser. Es ist nicht garantiert, welcher Kandidat geladen wird. Hat der Browser bereits ein größeres Bild im Cache, verwendet er es oft weiter, auch nach dem Verkleinern des Fensters. Welches Bild tatsächlich geladen wurde, zeigt currentSrc, nicht src.
w ohne sizes: Fehlt sizes, rechnet der Browser mit 100vw und lädt häufig unnötig große Dateien. Mit loading="lazy" ist auch sizes="auto" möglich, das aber noch nicht alle Browser unterstützen.
Deskriptoren nicht mischen: w und x dürfen im selben srcset nicht zusammen vorkommen. Doppelte Deskriptoren machen den Kandidaten ungültig.
Kommas in URLs: Da das Komma die Kandidaten trennt, sollten URLs mit Kommas (z. B. bei Bild-CDNs wie w_400,h_300) von einem Leerzeichen und Deskriptor gefolgt oder als %2C kodiert werden. Einfaches split(',') reicht dann zum Parsen nicht aus.
Verschiedene Bildformate oder Bildausschnitte (z. B. AVIF/WebP mit Rückfall oder anderer Zuschnitt je Breakpoint) gehören in ein <picture> mit <source>, nicht in srcset.
Reihenfolge beim Setzen per Skript: Setze sizes vor srcset bzw. vor dem Einfügen ins DOM. Sonst lädt der Browser eventuell zuerst einen unpassenden Kandidaten.
Sicherheit: URLs aus Nutzereingaben vor dem Zuweisen prüfen. Fremde Bildquellen können Tracking ermöglichen und werden von der CSP-Direktive img-src eingeschränkt.
Kompatibilität: Alle aktuellen Browser unterstützen srcset. Nur der Internet Explorer kennt es nicht und nutzt stattdessen src.

Siehe auch

HTMLImageElement.src HTMLImageElement.sizes HTMLImageElement.alt HTMLImageElement.border HTMLImageElement.height