Document.firstElementChild — Eigenschaft · JavaScript-Referenz

Signatur

Document.firstElementChild

Beschreibung

Document.firstElementChild stammt aus dem ParentNode-Mixin und gibt das erste direkte Kind des Dokuments zurück, das ein Element ist. Textknoten, Kommentare und die Doctype-Deklaration (<!DOCTYPE html>) werden übersprungen. Deshalb ist der Wert im Gegensatz zu document.firstChild nie ein DocumentType- oder Comment-Knoten.

Ein Dokument darf höchstens ein Wurzelelement haben. Darum liefert document.firstElementChild in der Praxis dasselbe wie document.documentElement, also bei HTML das <html>-Element und bei XML- oder SVG-Dokumenten deren Wurzelelement. Mit new Document() oder document.implementation.createDocument() lassen sich aber leere Dokumente ohne Wurzelelement erzeugen. Dann ist der Wert null.

Nützlich ist die Eigenschaft vor allem in allgemeinem Code, der gleich mit Document, DocumentFragment und Element umgehen soll, weil alle drei das ParentNode-Mixin umsetzen. Wenn Sie ausdrücklich das Wurzelelement meinen, ist document.documentElement meist lesbarer.

Rückgabewert

Typ

Element | null

Beschreibung

Das erste Kind-Element des Dokuments (in der Regel das Wurzelelement) oder null, wenn das Dokument kein Element enthält.

Beispiele

Wurzelelement eines HTML-Dokuments ermitteln

// Doctype und Kommentare vor <html> werden übersprungen
const root = document.firstElementChild;
console.log(root.tagName);
console.log(root === document.documentElement);

// Vergleich mit firstChild: liefert den Doctype-Knoten
console.log(document.firstChild.nodeName);

HTML true html

Leeres Dokument ohne Wurzelelement

const doc = new Document();
console.log(doc.firstElementChild); // noch kein Element vorhanden

const root = doc.createElement('config');
doc.appendChild(root);
console.log(doc.firstElementChild.nodeName);

null config

Geparstes XML-Dokument auswerten

const xml = `<?xml version="1.0"?>
<!-- Export -->
<users><user id="1">Anna</user></users>`;

const doc = new DOMParser().parseFromString(xml, 'application/xml');
const root = doc.firstElementChild;

console.log(root.nodeName);
console.log(root.firstElementChild.getAttribute('id'));

users 1

Allgemeine Hilfsfunktion für jeden ParentNode

// Funktioniert für Document, DocumentFragment und Element gleichermaßen
const firstTag = (parent) => parent.firstElementChild?.tagName.toLowerCase() ?? '(keins)';

const frag = document.createDocumentFragment();

console.log(firstTag(document));
console.log(firstTag(frag));
console.log(firstTag(document.body));

html (keins) (abhängig vom Inhalt, z. B. header)

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wie document.firstElementChild = el wird im nicht-strikten Modus stillschweigend ignoriert und löst im Strict Mode einen TypeError aus. Um das Wurzelelement auszutauschen, nutzen Sie document.replaceChild() bzw. replaceChildren().
Nicht mit firstChild verwechseln: document.firstChild ist in HTML-Dokumenten meist der DocumentType-Knoten, nicht <html>.
Auf null prüfen: Bei selbst erzeugten oder fehlerhaft geparsten Dokumenten kann der Wert null sein. Optional Chaining (?.) verhindert dann Laufzeitfehler. Beachten Sie auch, dass DOMParser bei ungültigem XML ein <parsererror>-Element als Wurzel liefert.
Live-Wert: Die Eigenschaft wird bei jedem Zugriff neu ermittelt und spiegelt den aktuellen DOM-Zustand wider.
Kompatibilität: Wird von allen modernen Browsern unterstützt. Auf Document und DocumentFragment fehlte die Eigenschaft in sehr alten Versionen (z. B. Internet Explorer), dort gab es sie nur auf Element. Als Ausweichlösung dient document.documentElement. In Node.js gibt es sie nur über DOM-Implementierungen wie jsdom.

Siehe auch

Document.lastElementChild Document.documentElement Document.childElementCount Document.children Node.firstChild Element.firstElementChild DocumentFragment.firstElementChild