Document.body — Eigenschaft · JavaScript-Referenz

Signatur

Document.body

Beschreibung

Die Eigenschaft document.body ist der schnellste Weg zum <body>-Element eines HTML-Dokuments. In alten Frameset-Dokumenten liefert sie stattdessen das äußerste <frameset>-Element. Gibt es keins von beiden, ist der Wert null.

Typische Einsatzzwecke: dynamisch erzeugte Elemente wie Modals, Toasts oder Overlays per appendChild() einhängen, Zustandsklassen am Body setzen (etwa dark-mode oder no-scroll) oder auf der gesamten Seite Ereignisse per Delegation abfangen.

Die Eigenschaft ist beschreibbar: Wenn man ihr ein neues <body>- oder <frameset>-Element zuweist, ersetzt es das bestehende Element samt allen Kindknoten. Andere Elementtypen führen zu einer HierarchyRequestError-DOMException.

Rückgabewert

Typ

HTMLBodyElement | HTMLFrameSetElement | null

Beschreibung

Das <body>- bzw. <frameset>-Element des Dokuments oder null, wenn keines existiert, z. B. weil das Skript im <head> läuft, bevor der Body geparst wurde.

Beispiele

Toast-Benachrichtigung an den Body anhängen

const showToast = (message, ms = 3000) => {
  const toast = document.createElement('div');
  toast.className = 'toast';
  toast.textContent = message; // textContent statt innerHTML – kein XSS
  document.body.append(toast);
  setTimeout(() => toast.remove(), ms);
};

showToast('Gespeichert!');
console.log(document.body.lastElementChild.className);

toast

Scrollen sperren, solange ein Modal offen ist

const openModal = () => {
  document.body.classList.add('no-scroll');
  document.body.style.overflow = 'hidden';
};

const closeModal = () => {
  document.body.classList.remove('no-scroll');
  document.body.style.overflow = '';
};

openModal();
console.log(document.body.classList.contains('no-scroll'));

true

Sicherer Zugriff, wenn das Skript im <head> läuft

const init = () => {
  document.body.dataset.ready = 'true';
  console.log('Body bereit:', document.body.tagName);
};

if (document.body) {
  init();
} else {
  document.addEventListener('DOMContentLoaded', init, { once: true });
}

Body bereit: BODY

Body komplett ersetzen

const newBody = document.createElement('body');
const h1 = document.createElement('h1');
h1.textContent = 'Wartungsmodus';
newBody.append(h1);

document.body = newBody; // ersetzt den alten Body samt Inhalt
console.log(document.body.firstElementChild.textContent);

try {
  document.body = document.createElement('div');
} catch (err) {
  console.log(err.name);
}

Wartungsmodus HierarchyRequestError

// Wichtig · Fallstricke

Hat den Wert null im <head>: Ein synchrones Skript im <head> läuft, bevor der Body geparst ist. Dann wirft document.body.appendChild() einen TypeError. Abhilfe schaffen defer, type="module", DOMContentLoaded oder ein Skript am Ende des Bodys.
In XML- oder SVG-Dokumenten ohne HTML-Body liefert die Eigenschaft ebenfalls null.
Wer document.body neu zuweist, verliert alle Kindknoten und die daran gebundenen Event-Listener.
Das Gegenstück zu document.body ist document.documentElement (<html>). Das Scrollen des gesamten Viewports läuft im Standardmodus über document.documentElement bzw. document.scrollingElement, nicht über body.
Sicherheit: Nicht vertrauenswürdige Inhalte nie per document.body.innerHTML einfügen (XSS). Stattdessen textContent oder DOM-Methoden verwenden.
Die Eigenschaft wird von allen Browsern seit Langem unterstützt. <frameset> gilt in HTML5 als veraltet.

Siehe auch

Document.documentElement Document.head Document.scrollingElement HTMLBodyElement Element.append() CSSSkewY.ay