HTMLLinkElement.imageSizes — Eigenschaft · JavaScript-Referenz

Signatur

HTMLLinkElement.imageSizes

Beschreibung

Die Eigenschaft imageSizes spiegelt das Attribut imagesizes eines <link>-Elements wider. Sie arbeitet mit imageSrcset zusammen und entspricht dem Attribut sizes eines <img>-Elements: Eine kommagetrennte Liste aus Media-Conditions und Längenangaben (z. B. (max-width: 600px) 100vw, 50vw) teilt dem Browser mit, wie breit das Bild später dargestellt wird.

Wichtig ist das vor allem beim Vorladen responsiver Bilder mit rel="preload" und as="image". Mit imageSrcset und imageSizes wählt der Browser schon beim Preload dieselbe Bildvariante aus, die das spätere <img> mit srcset/sizes anfordern würde. So wird nichts doppelt geladen. Typisch ist das für LCP-Bilder (Hero-Bilder), um den Largest Contentful Paint zu verbessern.

Der Wert ist ein einfacher String. Das Lesen liefert den Attributwert oder einen leeren String, wenn das Attribut fehlt. Das Schreiben setzt das Attribut imagesizes. Der Browser prüft den Inhalt dabei nicht auf Gültigkeit: Ungültige Angaben werden erst beim Auswählen der Bildquelle ignoriert.

Parameter

Name	Typ	Default	Beschreibung
$value	string	""	Nur beim Setzen: eine `sizes`-Liste im gleichen Format wie beim `<img>`-Attribut `sizes`, z. B. `"(max-width: 800px) 100vw, 800px"`.

Rückgabewert

Typ

string

Beschreibung

Der aktuelle Wert des Attributs imagesizes oder ein leerer String, wenn es nicht gesetzt ist.

Beispiele

Wert eines vorhandenen Preload-Links auslesen

// HTML:
// <link rel="preload" as="image"
//       href="hero-800.jpg"
//       imagesrcset="hero-400.jpg 400w, hero-800.jpg 800w, hero-1600.jpg 1600w"
//       imagesizes="(max-width: 600px) 100vw, 50vw">

const link = document.querySelector('link[rel="preload"][as="image"]');
console.log(link.imageSizes);
console.log(link.imageSrcset);

(max-width: 600px) 100vw, 50vw hero-400.jpg 400w, hero-800.jpg 800w, hero-1600.jpg 1600w

Responsives Hero-Bild dynamisch vorladen

const preloadResponsiveImage = ({ src, srcset, sizes }) => {
  const link = document.createElement('link');
  link.rel = 'preload';
  link.as = 'image';
  link.href = src; // Fallback für Browser ohne imagesrcset-Unterstützung
  link.imageSrcset = srcset;
  link.imageSizes = sizes;
  document.head.append(link);
  return link;
};

const link = preloadResponsiveImage({
  src: '/img/hero-800.webp',
  srcset: '/img/hero-400.webp 400w, /img/hero-800.webp 800w, /img/hero-1600.webp 1600w',
  sizes: '(max-width: 700px) 100vw, 700px'
});

console.log(link.getAttribute('imagesizes'));

(max-width: 700px) 100vw, 700px

Feature-Erkennung und Standardwert

const supportsImageSizes = 'imageSizes' in HTMLLinkElement.prototype;
console.log('imageSizes unterstützt:', supportsImageSizes);

const link = document.createElement('link');
console.log(JSON.stringify(link.imageSizes)); // Attribut fehlt → leerer String

link.imageSizes = '100vw';
console.log(link.outerHTML);

imageSizes unterstützt: true "" <link imagesizes="100vw">

// Wichtig · Fallstricke

Nur zusammen mit imageSrcset sinnvoll: Ohne imagesrcset mit w-Angaben hat imageSizes keine Wirkung. Bei Dichte-Angaben wie 1x oder 2x wird sizes nicht beachtet.
Werte müssen übereinstimmen: imageSizes/imageSrcset des Preload-Links müssen genau zu sizes/srcset des späteren <img> passen. Sonst lädt der Browser womöglich eine andere Variante und das Bild wird doppelt übertragen. In der Konsole erscheint dann oft die Warnung „preloaded but not used“.
Setzen Sie href als Fallback: Ältere Browser (etwa Safari vor 17.2) kennen imagesrcset nicht und laden sonst gar nichts vor. Unterstützende Browser ignorieren href, sobald imagesrcset vorhanden ist.
Die Groß- und Kleinschreibung unterscheidet sich: Die Eigenschaft heißt imageSizes (camelCase), das HTML-Attribut imagesizes (klein geschrieben).
Der Browser prüft den Wert nicht. Ein Tippfehler wirft keinen Fehler, sondern führt meist dazu, dass der Browser mit dem Standardwert 100vw rechnet und dadurch eine zu große Bildvariante lädt.
Ein Preload greift nur, wenn der Link früh im Dokument steht. Wird er per JavaScript erst spät eingefügt, bringt er für LCP-Bilder oft wenig. Dann ist statisches HTML oder fetchpriority=\"high\" am <img> vorzuziehen.

Siehe auch

HTMLLinkElement.imageSrcset HTMLLinkElement.sizes HTMLLinkElement.media HTMLLinkElement.as HTMLLinkElement.disabled