HTMLHeadElement — Schnittstelle · JavaScript-Referenz

Signatur

interface HTMLHeadElement extends HTMLElement

Beschreibung

HTMLHeadElement ist die DOM-Schnittstelle für das <head>-Element eines HTML-Dokuments. Sie erbt alle Eigenschaften und Methoden von HTMLElement und fügt selbst keine eigenen, standardisierten Mitglieder hinzu. Das Element enthält Metadaten wie <title>, <meta>, <link>, <style>, <script> und <base>.

Der einfachste Zugriff läuft über document.head. Diese Eigenschaft liefert direkt das HTMLHeadElement des aktuellen Dokuments. Man braucht die Schnittstelle vor allem, um zur Laufzeit Ressourcen einzubinden, zum Beispiel Stylesheets, Skripte, preload- oder preconnect-Hinweise. Auch Meta-Tags wie theme-color, Canonical-Links oder Open-Graph-Angaben in Single-Page-Anwendungen lassen sich so dynamisch anpassen.

Ein <head>-Element erzeugt der Parser immer automatisch, auch wenn es im Markup fehlt. Pro Dokument sollte es genau eines geben. Elemente, die dort nicht erlaubt sind, verschiebt der Parser beim Einlesen in den <body>.

Rückgabewert

Typ

HTMLHeadElement

Beschreibung

Über document.head bekommt man die Instanz des <head>-Elements im aktuellen Dokument.

Beispiele

Zugriff auf das head-Element und Typprüfung

const head = document.head;
console.log(head instanceof HTMLHeadElement);
console.log(head === document.querySelector('head'));
console.log(head.children.length > 0);

true true true

Stylesheet dynamisch nachladen

const loadStylesheet = (href) => new Promise((resolve, reject) => {
  const link = document.createElement('link');
  link.rel = 'stylesheet';
  link.href = href;
  link.onload = () => resolve(link);
  link.onerror = () => reject(new Error(`Konnte ${href} nicht laden`));
  document.head.append(link);
});

await loadStylesheet('/css/dark-theme.css');
console.log('Dunkles Theme aktiv');

Dunkles Theme aktiv

Meta-Tag setzen oder aktualisieren (SPA)

const setMeta = (name, content) => {
  let meta = document.head.querySelector(`meta[name="${name}"]`);
  if (!meta) {
    meta = document.createElement('meta');
    meta.name = name;
    document.head.append(meta);
  }
  meta.content = content;
  return meta;
};

setMeta('description', 'Produktseite: Ergonomische Tastatur');
setMeta('theme-color', '#0a7cff');
console.log(document.head.querySelector('meta[name="theme-color"]').content);

#0a7cff

Neues head-Element per Konstruktor-Weg erzeugen

// HTMLHeadElement hat keinen eigenen Konstruktor, man erzeugt es über createElement
const doc = document.implementation.createHTMLDocument('Vorschau');
const head = doc.head;
const base = doc.createElement('base');
base.href = 'https://example.com/';
head.prepend(base);
console.log(head.firstElementChild.tagName, doc.createElement('head') instanceof HTMLHeadElement);

BASE true

// Wichtig · Fallstricke

Keine eigenen Mitglieder: Die frühere Eigenschaft profile ist veraltet und wurde entfernt. Man sollte sie nicht mehr verwenden.
Kein direkter Konstruktor: new HTMLHeadElement() wirft einen TypeError („Illegal constructor“). Stattdessen nutzt man document.createElement('head') oder document.head.
Reihenfolge beachten: <meta charset> und <base> müssen früh stehen. Ein nachträglich per JavaScript eingefügtes <base> wirkt sich nur auf URLs aus, die danach aufgelöst werden. Eine Zeichensatz-Angabe, die man per Skript einfügt, bleibt wirkungslos.
Dynamische Skripte: Skripte, die per createElement('script') in den head eingefügt werden, laden standardmäßig asynchron. Wenn die Reihenfolge wichtig ist, setzt man script.async = false.
Sicherheit: Wenn Skripte, Stylesheets oder Meta-Tags aus Benutzereingaben entstehen, droht XSS. Man sollte keine ungeprüften URLs oder innerHTML auf document.head verwenden und eine Content Security Policy (CSP) einsetzen.
SEO: Nicht jeder Crawler führt JavaScript aus. Meta-Angaben, die erst per JavaScript gesetzt werden, erkennen Crawler deshalb unter Umständen nicht.
Kompatibilität: document.head und HTMLHeadElement werden in allen modernen Browsern unterstützt.

Siehe auch

HTMLElement Document.head HTMLTitleElement HTMLMetaElement HTMLLinkElement HTMLBaseElement Document.createElement()