HTMLMediaElement.loading — Eigenschaft · JavaScript-Referenz

Signatur

HTMLMediaElement.loading

Beschreibung

Die Eigenschaft loading der Schnittstelle HTMLMediaElement spiegelt das HTML-Attribut loading von <video>- und <audio>-Elementen wider. Damit gibt man dem Browser einen Hinweis, ob er die Medienressource sofort laden soll oder erst, wenn sich das Element dem sichtbaren Bereich (Viewport) nähert.

Zwei Werte sind möglich:

"eager" – Standardwert: Das Medium wird wie gewohnt sofort geladen, egal wo das Element auf der Seite steht (abhängig von preload und autoplay).
"lazy" – Das Laden wird aufgeschoben, bis das Element voraussichtlich bald sichtbar wird. Bei <video> betrifft das auch das Laden der Metadaten und in der Regel das poster-Bild.

Das Konzept entspricht dem schon lange etablierten loading-Attribut von <img> und <iframe>. Sinnvoll ist "lazy" vor allem bei langen Seiten mit vielen eingebetteten Videos oder Audiodateien weiter unten (Galerien, Blog-Artikel, Produktseiten): Man spart Bandbreite und verbessert die Ladezeit des sichtbaren Bereichs. Medien im ersten sichtbaren Bildschirm („above the fold“) sollten hingegen "eager" bleiben.

Da es sich nur um einen Hinweis handelt, entscheidet der Browser selbst über die genaue Distanz zum Viewport, ab der geladen wird. Die Eigenschaft sollte gesetzt werden, bevor die Quelle (src oder <source>) zugewiesen wird – idealerweise direkt im HTML-Markup.

Parameter

Name	Typ	Default	Beschreibung
$value	"eager" \| "lazy"	"eager"	Beim Setzen: der gewünschte Lade-Hinweis. Ungültige Werte werden beim Auslesen als `"eager"` interpretiert (aufgezählte Attribut-Spiegelung).

Rückgabewert

Typ

string

Beschreibung

"lazy", wenn verzögertes Laden aktiv ist, sonst "eager" (auch bei fehlendem oder ungültigem Attribut).

Beispiele

Wert auslesen und per Skript setzen

// HTML: <video id="demo" controls loading="lazy"></video>
const video = document.querySelector('#demo');
console.log(video.loading);

// Vor dem Zuweisen der Quelle wieder auf sofortiges Laden umstellen
video.loading = 'eager';
video.src = '/media/intro.mp4';
console.log(video.getAttribute('loading'));

lazy eager

Feature-Erkennung mit Fallback über IntersectionObserver

const supportsLazyMedia = 'loading' in HTMLMediaElement.prototype;

// HTML: <video class="lazy-video" data-src="/media/clip.mp4" controls></video>
const videos = document.querySelectorAll('video.lazy-video');

if (supportsLazyMedia) {
  videos.forEach((video) => {
    video.loading = 'lazy';
    video.src = video.dataset.src;
  });
} else {
  const observer = new IntersectionObserver((entries, obs) => {
    entries.forEach((entry) => {
      if (!entry.isIntersecting) return;
      const video = entry.target;
      video.src = video.dataset.src;
      obs.unobserve(video);
    });
  }, { rootMargin: '300px' });

  videos.forEach((video) => observer.observe(video));
}

console.log(supportsLazyMedia ? 'natives Lazy Loading' : 'IntersectionObserver-Fallback');

natives Lazy Loading (bzw. IntersectionObserver-Fallback in älteren Browsern)

Dynamisch erzeugte Audio-Elemente verzögert laden

const tracks = ['/audio/folge-1.mp3', '/audio/folge-2.mp3', '/audio/folge-3.mp3'];
const list = document.querySelector('#podcast-list');

tracks.forEach((url) => {
  const audio = document.createElement('audio');
  audio.controls = true;
  audio.loading = 'lazy'; // vor src setzen!
  audio.preload = 'metadata';
  audio.src = url;
  list.append(audio);
});

console.log([...list.querySelectorAll('audio')].map((a) => a.loading));

["lazy", "lazy", "lazy"]

Ungültige Werte fallen auf "eager" zurück

const video = document.createElement('video');
console.log(video.loading);

video.setAttribute('loading', 'irgendwann');
console.log(video.loading);
console.log(video.getAttribute('loading'));

eager eager irgendwann

// Wichtig · Fallstricke

Kompatibilität: Die Eigenschaft ist neu und experimentell; die Unterstützung ist noch lückenhaft. Immer per 'loading' in HTMLMediaElement.prototype prüfen und bei Bedarf auf IntersectionObserver ausweichen. Browser ohne Unterstützung ignorieren das Attribut einfach und laden sofort.
Reihenfolge beachten: Wird loading = 'lazy' erst gesetzt, nachdem src zugewiesen wurde, kann der Ladevorgang bereits begonnen haben – dann bringt der Hinweis nichts mehr.
Zusammenspiel mit autoplay und preload: Bei "lazy" wird auch ein autoplay-Video erst abgespielt, wenn es in die Nähe des Viewports kommt. preload bestimmt weiterhin, wie viel geladen wird, sobald das Laden startet.
Nicht für sichtbare Medien: "lazy" bei Medien im ersten Bildschirm verzögert deren Anzeige unnötig und kann Kennzahlen wie LCP verschlechtern.
Explizite Aufrufe wie load() oder play() können das Laden unabhängig vom Hinweis anstoßen.
Der Wert ist nur ein Hinweis – die Schwelle, ab der geladen wird, legt der Browser fest (u. a. abhängig von der Netzwerkverbindung).

Siehe auch

HTMLMediaElement.seeking HTMLMediaElement.loop HTMLMediaElement.duration HTMLMediaElement.ended HTMLMediaElement.paused