Document.documentElement — Eigenschaft · JavaScript-Referenz

Signatur

get Document.documentElement

Beschreibung

document.documentElement gibt das Wurzelelement eines Dokuments als Element-Objekt zurück. In HTML-Dokumenten ist das immer das <html>-Element (ein HTMLHtmlElement), in SVG-Dokumenten das äußerste <svg> und in beliebigen XML-Dokumenten das jeweilige Wurzelelement.

In der Praxis braucht man die Eigenschaft vor allem, um globale Zustände am Wurzelelement zu setzen, etwa Klassen oder data-*-Attribute für Themes (Dunkelmodus), die Sprache per lang-Attribut oder CSS-Custom-Properties (--variable), die auf der ganzen Seite gelten. Außerdem liefert sie im Standardmodus die Maße des Viewports (clientWidth, clientHeight) und die Scrollposition der Seite (scrollTop, scrollHeight).

Im Unterschied zu document.body (dem <body>-Element) und document.head steht documentElement ganz oben im Elementbaum. Über dem Wurzelelement gibt es nur noch den Document-Knoten selbst, also document.documentElement.parentNode === document.

Die Eigenschaft ist schreibgeschützt. Um das Wurzelelement auszutauschen, nutzt man DOM-Methoden wie document.replaceChild(). Das ist aber nur selten sinnvoll.

Rückgabewert

Typ

Element | null

Beschreibung

Das Wurzelelement des Dokuments. Bei HTML ein HTMLHtmlElement. null nur dann, wenn das Dokument kein Wurzelelement hat, z. B. bei einem leer erzeugten Dokument.

Beispiele

Wurzelelement prüfen

const root = document.documentElement;
console.log(root.tagName);
console.log(root.parentNode === document);
console.log(root instanceof HTMLHtmlElement);

HTML true true

Dunkelmodus per data-Attribut am <html>-Element umschalten

const root = document.documentElement;

const setTheme = (theme) => {
  root.dataset.theme = theme; // erzeugt data-theme="dark" bzw. "light"
  localStorage.setItem('theme', theme);
};

const toggleTheme = () =>
  setTheme(root.dataset.theme === 'dark' ? 'light' : 'dark');

// Gespeicherte Wahl oder Systemeinstellung übernehmen
const prefersDark = matchMedia('(prefers-color-scheme: dark)').matches;
setTheme(localStorage.getItem('theme') ?? (prefersDark ? 'dark' : 'light'));

document.querySelector('#theme-toggle')?.addEventListener('click', toggleTheme);
// CSS: [data-theme="dark"] { --bg: #111; --fg: #eee; }

Globale CSS-Variable setzen und Sprache auslesen

const root = document.documentElement;

// Custom Property für die ganze Seite setzen
root.style.setProperty('--header-height', '64px');

// Berechneten Wert auslesen
const height = getComputedStyle(root).getPropertyValue('--header-height');
console.log(height.trim());

// Dokumentsprache (lang-Attribut von <html>)
console.log(root.lang || 'keine Sprache gesetzt');

64px de

Scrollfortschritt der Seite berechnen

const root = document.documentElement;

const updateProgress = () => {
  const max = root.scrollHeight - root.clientHeight;
  const percent = max > 0 ? Math.round((root.scrollTop / max) * 100) : 0;
  root.style.setProperty('--scroll-progress', `${percent}%`);
  console.log(`Gescrollt: ${percent} %`);
};

window.addEventListener('scroll', updateProgress, { passive: true });
updateProgress();

Gescrollt: 0 %

// Wichtig · Fallstricke

Schreibgeschützt: Wer document.documentElement etwas zuweist, bewirkt nichts; im Strict Mode gibt es einen TypeError. Das zurückgegebene Element selbst lässt sich aber normal verändern (Attribute, Klassen, Styles).
Quirks-Modus: Ohne <!DOCTYPE html> liefern scrollTop und clientHeight der Seite ihre Werte teils über document.body statt über documentElement. Für die Scrollposition ist document.scrollingElement oder window.scrollY zuverlässiger.
clientWidth vs. window.innerWidth: documentElement.clientWidth zählt die Breite der Scrollleiste nicht mit, innerWidth schon.
Bei Dokumenten, die mit document.implementation.createDocument(null, null) erzeugt wurden, kann der Wert null sein. Vor dem Zugriff also prüfen.
Kompatibilität: Wird von allen Browsern unterstützt, auch von sehr alten, und funktioniert ebenso in XML- und SVG-Dokumenten.

Siehe auch

Document.body Document.head Document.scrollingElement Element.classList HTMLElement.dataset HTMLHtmlElement Document.rootElement