HTMLIFrameElement.loading — Eigenschaft · JavaScript-Referenz

Signatur

HTMLIFrameElement.loading

Beschreibung

Die Eigenschaft loading spiegelt das HTML-Attribut loading eines <iframe>-Elements wider. Sie gibt dem Browser einen Hinweis, wie er mit dem Laden des eingebetteten Dokuments umgehen soll. Erlaubt sind zwei Werte:

"eager" (Standard): Das iframe wird sofort geladen, egal ob es gerade sichtbar ist.
"lazy": Der Browser schiebt das Laden auf, bis das iframe in die Nähe des sichtbaren Bereichs (Viewport) kommt. Wie groß dieser Abstand ist, legt der Browser selbst fest.

Lazy Loading lohnt sich vor allem bei Einbettungen, die weiter unten auf der Seite liegen, etwa YouTube-Videos, Karten, Social-Media-Widgets oder Werbeflächen. So spart die Seite Bandbreite, Arbeitsspeicher und CPU-Zeit, und Kennzahlen wie Largest Contentful Paint oder Time to Interactive verbessern sich. Für iframes, die direkt beim Seitenaufruf sichtbar sind, sollte "eager" gesetzt bleiben.

Die Eigenschaft ist ein aufgezähltes Attribut (enumerated attribute). Ungültige oder fehlende Werte werden beim Lesen als "eager" zurückgegeben. Wer die Eigenschaft setzt, ändert auch das zugehörige HTML-Attribut. Wichtig ist der richtige Zeitpunkt: Der Wert muss gesetzt werden, bevor das iframe ein src bekommt oder ins Dokument eingefügt wird. Sonst hat das Laden womöglich schon begonnen.

Parameter

Name	Typ	Default	Beschreibung
$value	"eager" \| "lazy"	"eager"	Neuer Wert beim Setzen der Eigenschaft. Bei `"lazy"` wird das Laden aufgeschoben, bei `"eager"` wird sofort geladen. Andere Werte gelten beim Lesen als `"eager"`.

Rückgabewert

Typ

string

Beschreibung

Der aktuelle Lade-Hinweis: "eager" oder "lazy". Fehlt das Attribut oder ist sein Wert ungültig, wird "eager" zurückgegeben.

Beispiele

iframe dynamisch mit Lazy Loading erzeugen

const iframe = document.createElement('iframe');
// Zuerst loading setzen, danach src – sonst lädt der Browser womöglich sofort
iframe.loading = 'lazy';
iframe.src = 'https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ';
iframe.width = 560;
iframe.height = 315;
iframe.title = 'Produktvideo';

document.querySelector('#video-bereich').append(iframe);
console.log(iframe.loading);
console.log(iframe.getAttribute('loading'));

lazy lazy

Standardwert und ungültige Werte auslesen

const frame = document.createElement('iframe');
console.log(frame.loading); // kein Attribut gesetzt

frame.setAttribute('loading', 'irgendwann');
console.log(frame.loading); // ungültiger Wert

frame.setAttribute('loading', 'LAZY');
console.log(frame.loading); // Groß-/Kleinschreibung spielt keine Rolle

eager eager lazy

Feature-Erkennung mit Fallback über IntersectionObserver

const supportsLazy = 'loading' in HTMLIFrameElement.prototype;

const frames = document.querySelectorAll('iframe[data-src]');

if (supportsLazy) {
  frames.forEach((frame) => {
    frame.loading = 'lazy';
    frame.src = frame.dataset.src;
  });
} else {
  // Fallback für ältere Browser
  const observer = new IntersectionObserver((entries, obs) => {
    entries.forEach((entry) => {
      if (entry.isIntersecting) {
        entry.target.src = entry.target.dataset.src;
        obs.unobserve(entry.target);
      }
    });
  }, { rootMargin: '200px' });

  frames.forEach((frame) => observer.observe(frame));
}

console.log(`Natives Lazy Loading: ${supportsLazy}`);

Natives Lazy Loading: true

Sichtbare Einbettungen gezielt sofort laden

// Alle iframes lazy laden, außer die im ersten Bildschirm sichtbaren
document.querySelectorAll('iframe').forEach((frame) => {
  const rect = frame.getBoundingClientRect();
  const imViewport = rect.top < window.innerHeight;
  frame.loading = imViewport ? 'eager' : 'lazy';
  console.log(frame.title, '→', frame.loading);
});

Karte → eager Kommentare → lazy

// Wichtig · Fallstricke

Nur ein Hinweis: Der Browser entscheidet selbst, wann ein lazy-iframe tatsächlich geladen wird. Der Abstand zum Viewport kann je nach Browser und Verbindungsqualität unterschiedlich sein.
Reihenfolge beachten: Wird loading = 'lazy' erst gesetzt, nachdem src zugewiesen und das Element eingefügt wurde, hat das Laden womöglich schon begonnen. Die Änderung bewirkt dann nichts mehr.
JavaScript deaktiviert: Die Spezifikation sieht vor, dass Lazy Loading bei abgeschaltetem Scripting nicht greift. Damit soll verhindert werden, dass Seiten die Scroll-Position über nachgeladene Inhalte verfolgen.
Versteckte iframes (z. B. display: none oder Größe 0×0) werden bei \"lazy\" unter Umständen nie oder zu einem unerwarteten Zeitpunkt geladen. Für unsichtbare Tracking- oder Kommunikations-iframes sollte deshalb \"eager\" gesetzt bleiben.
Das load-Ereignis des Fensters wartet nicht auf lazy-iframes außerhalb des sichtbaren Bereichs. Code, der beim Seiten-load auf contentWindow zugreift, findet dort unter Umständen noch kein fertig geladenes Dokument.
Kompatibilität: Chromium-Browser unterstützen die Eigenschaft seit Version 77, Safari seit 16.4, Firefox erst seit Version 121 (Ende 2023). Ältere Browser ignorieren das Attribut und laden sofort. Deshalb vorher mit 'loading' in HTMLIFrameElement.prototype prüfen.

Siehe auch

HTMLFencedFrameElement.width HTMLIFrameElement.browsingTopics HTMLIFrameElement.allow HTMLIFrameElement.name HTMLIFrameElement.sandbox