Document.fullscreenElement — Eigenschaft · JavaScript-Referenz

Signatur

get Document.fullscreenElement

Beschreibung

Die schreibgeschützte Eigenschaft document.fullscreenElement gehört zur Fullscreen-API. Sie liefert das Element, das zuletzt per Element.requestFullscreen() in den Vollbildmodus gewechselt ist, oder null, wenn gerade kein Element im Vollbild angezeigt wird.

Am häufigsten wird sie genutzt, um den aktuellen Zustand abzufragen, etwa für einen Umschalt-Button („Vollbild an/aus“), oder um im fullscreenchange-Ereignis festzustellen, ob der Vollbildmodus gerade betreten oder verlassen wurde. Ein einfacher Wahrheitswert-Test (!!document.fullscreenElement) reicht dafür aus.

Die Eigenschaft gibt es auch auf ShadowRoot. Liegt das Vollbild-Element in einem Shadow-DOM, gibt document.fullscreenElement nur den Host zurück, der im Dokument sichtbar ist (Retargeting). Bei verschachtelten Vollbild-Anfragen wird immer das oberste Element des Vollbild-Stapels geliefert.

Rückgabewert

Typ

Element | null

Beschreibung

Das Element, das gerade im Vollbildmodus angezeigt wird, oder null, wenn kein Vollbild aktiv ist.

Beispiele

Vollbild mit einem Button umschalten

const player = document.querySelector('#video-player');
const toggleBtn = document.querySelector('#fullscreen-toggle');

toggleBtn.addEventListener('click', async () => {
  try {
    if (document.fullscreenElement) {
      // Es ist bereits ein Element im Vollbild → beenden
      await document.exitFullscreen();
    } else {
      await player.requestFullscreen();
    }
  } catch (err) {
    console.error('Vollbild fehlgeschlagen:', err.message);
  }
});

Zustand im fullscreenchange-Ereignis auswerten

document.addEventListener('fullscreenchange', () => {
  const el = document.fullscreenElement;
  if (el) {
    console.log(`Vollbild aktiv: <${el.tagName.toLowerCase()} id="${el.id}">`);
    document.body.classList.add('is-fullscreen');
  } else {
    console.log('Vollbild beendet');
    document.body.classList.remove('is-fullscreen');
  }
});

Vollbild aktiv: <div id="video-player"> Vollbild beendet

Prüfen, ob ein bestimmtes Element im Vollbild ist (mit Präfix-Fallback)

const getFullscreenElement = () =>
  document.fullscreenElement ?? document.webkitFullscreenElement ?? null;

const isInFullscreen = (element) => getFullscreenElement() === element;

const canvas = document.querySelector('canvas');
console.log(isInFullscreen(canvas));

false

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung an document.fullscreenElement hat keine Wirkung. Um den Vollbildmodus zu starten oder zu beenden, nutzt man element.requestFullscreen() bzw. document.exitFullscreen().
Kompatibilität: Ältere Safari-Versionen (vor 16.4) kennen nur die Variante mit Präfix, document.webkitFullscreenElement. Ganz alte Firefox-Versionen verwenden mozFullScreenElement. Auf dem iPhone unterstützt Safari die Fullscreen-API für beliebige Elemente nicht; dort geht nur Video-Vollbild über webkitEnterFullscreen().
Ein Vollbild, das der Nutzer per F11 auslöst, ist ein Browser-Vollbild und kein Vollbild der API. In diesem Fall bleibt fullscreenElement null.
In iframes funktioniert Vollbild nur mit dem Attribut allow="fullscreen". Ist das iframe selbst im Vollbild, liefert document.fullscreenElement des übergeordneten Dokuments das <iframe>-Element.
Den Zustand direkt nach requestFullscreen() abzufragen, ist unzuverlässig. Besser auf das zurückgegebene Promise oder auf das Ereignis fullscreenchange warten.

Siehe auch

Element.requestFullscreen() Document.exitFullscreen() Document.fullscreenEnabled ShadowRoot.fullscreenElement Document.fullscreen