HTMLHtmlElement — Schnittstelle · JavaScript-Referenz

Signatur

interface HTMLHtmlElement extends HTMLElement

Beschreibung

HTMLHtmlElement ist die DOM-Schnittstelle für das <html>-Element, das oberste Element jedes HTML-Dokuments. Sie erbt alle Eigenschaften und Methoden von HTMLElement, Element und Node. Eigene Eigenschaften bringt sie praktisch nicht mehr mit: Nur die veraltete Eigenschaft version gibt es noch.

In der Praxis greift man über document.documentElement auf das Element zu. Typische Anwendungsfälle sind:

die Dokumentsprache über lang lesen oder setzen, etwa für Barrierefreiheit und Silbentrennung,
die Schreibrichtung über dir festlegen,
seitenweite Zustandsklassen (z. B. dark oder no-js) über classList umschalten,
CSS-Custom-Properties global über style.setProperty() setzen, weil sie für :root gelten,
Scroll-Position und Viewport-Maße über scrollTop und clientHeight auslesen,
den Vollbildmodus der ganzen Seite mit requestFullscreen() starten.

Da es pro Dokument nur ein Wurzelelement gibt, erzeugt man HTMLHtmlElement kaum selbst. Das geht höchstens mit document.createElement('html') oder beim Aufbau eines neuen Dokuments über document.implementation.createHTMLDocument().

Parameter

Name	Typ	Default	Beschreibung
$version	string	""	Veraltet. Spiegelt das Attribut `version` (DTD-Version) wider. Hat in HTML5 keine Wirkung mehr und sollte nicht verwendet werden.

Rückgabewert

Typ

HTMLHtmlElement

Beschreibung

document.documentElement liefert in HTML-Dokumenten eine Instanz von HTMLHtmlElement.

Beispiele

Wurzelelement abrufen und Typ prüfen

const root = document.documentElement;
console.log(root instanceof HTMLHtmlElement);
console.log(root.tagName);
console.log(root.lang || '(keine Sprache gesetzt)');

true HTML de

Dark-Mode seitenweit per Klasse und CSS-Variable umschalten

const root = document.documentElement;

const setTheme = (dark) => {
  root.classList.toggle('dark', dark);
  root.style.setProperty('--bg', dark ? '#111' : '#fff');
  localStorage.setItem('theme', dark ? 'dark' : 'light');
};

const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
setTheme(localStorage.getItem('theme') === 'dark' || prefersDark);
console.log(root.className);

dark

Sprache und Schreibrichtung dynamisch setzen

const applyLocale = (locale) => {
  const root = document.documentElement;
  root.lang = locale;
  root.dir = ['ar', 'he', 'fa'].includes(locale.split('-')[0]) ? 'rtl' : 'ltr';
  return `${root.lang} / ${root.dir}`;
};

console.log(applyLocale('ar-EG'));
console.log(applyLocale('de-DE'));

ar-EG / rtl de-DE / ltr

Neues Dokument erzeugen und dessen Wurzel bearbeiten

const doc = document.implementation.createHTMLDocument('Vorschau');
const html = doc.documentElement;
html.setAttribute('lang', 'en');
console.log(html instanceof HTMLHtmlElement, html.outerHTML.slice(0, 16));

true <html lang="en">

// Wichtig · Fallstricke

Veraltet: Die Eigenschaft version ist veraltet und hat keine Wirkung. Nicht verwenden.
In XML- oder SVG-Dokumenten liefert document.documentElement kein HTMLHtmlElement, sondern z. B. ein SVGSVGElement. Vor HTML-spezifischem Code am besten mit instanceof prüfen.
Die Scroll-Position des Dokuments liest man verlässlicher über document.scrollingElement oder window.scrollY aus. Im alten Quirks-Modus ist nämlich body das scrollende Element und nicht html.
Theme-Klassen möglichst früh setzen, z. B. mit einem kleinen Inline-Skript im <head>. Sonst blitzt beim Laden kurz das falsche Farbschema auf (FOUC). Achtung: Eine strenge Content Security Policy (CSP) blockiert solche Inline-Skripte, wenn sie nicht per Nonce oder Hash freigegeben sind.
Die Schnittstelle wird von allen Browsern unterstützt.

Siehe auch

HTMLSpanElement HTMLHRElement HTMLHeadElement HTMLStyleElement HTMLTimeElement