HTMLHeadingElement — Schnittstelle · JavaScript-Referenz

Signatur

interface HTMLHeadingElement extends HTMLElement

Beschreibung

HTMLHeadingElement ist die DOM-Schnittstelle für alle sechs Überschriften-Ebenen <h1> bis <h6>. Alle Überschriften teilen sich diese eine Schnittstelle. Die Ebene erkennt man also nicht am Typ, sondern an tagName bzw. localName (z. B. "H2" bzw. "h2").

Die Schnittstelle bringt außer der veralteten Eigenschaft align keine eigenen Mitglieder mit. Alles, was man im Alltag braucht (textContent, id, classList, dataset, scrollIntoView() usw.), kommt von HTMLElement, Element und Node.

Typische Einsatzfälle sind automatisch erzeugte Inhaltsverzeichnisse, Sprungmarken („Deep Links“) an Überschriften, Prüfungen der Überschriften-Hierarchie für die Barrierefreiheit und das dynamische Anlegen von Abschnittsüberschriften. Mit instanceof HTMLHeadingElement lässt sich zuverlässig prüfen, ob ein Element eine Überschrift ist, egal welcher Ebene.

Parameter

Name	Typ	Default	Beschreibung
$align	string	""	Veraltet. Spiegelt das HTML-Attribut `align` wider (`"left"`, `"right"`, `"center"`, `"justify"`). Stattdessen CSS `text-align` verwenden.

Rückgabewert

Typ

HTMLHeadingElement

Beschreibung

Instanzen entstehen über document.createElement("h1") bis ("h6") oder durch das Parsen von HTML. Einen öffentlichen Konstruktor gibt es nicht.

Beispiele

Überschrift erzeugen und Typ prüfen

const h2 = document.createElement('h2');
h2.textContent = 'Installation';
h2.id = 'installation';
document.body.append(h2);

console.log(h2 instanceof HTMLHeadingElement);
console.log(h2.tagName);
console.log(Number(h2.localName.slice(1))); // Ebene als Zahl

true H2 2

Inhaltsverzeichnis automatisch erzeugen

const slugify = (text) => text.toLowerCase().trim()
  .replace(/[^a-z0-9äöüß]+/g, '-').replace(/^-|-$/g, '');

const headings = [...document.querySelectorAll('article h2, article h3')];
const toc = document.createElement('ul');

for (const h of headings) {
  h.id ||= slugify(h.textContent);
  const li = document.createElement('li');
  li.style.marginLeft = h.localName === 'h3' ? '1em' : '0';
  const a = document.createElement('a');
  a.href = `#${h.id}`;
  a.textContent = h.textContent;
  li.append(a);
  toc.append(li);
}

document.querySelector('#toc')?.append(toc);

Überschriften-Hierarchie auf Sprünge prüfen (Barrierefreiheit)

const levels = [...document.querySelectorAll('h1, h2, h3, h4, h5, h6')]
  .map((h) => ({ el: h, level: Number(h.localName[1]) }));

levels.forEach(({ el, level }, i) => {
  const prev = levels[i - 1]?.level ?? 0;
  if (level > prev + 1) {
    console.warn(`Sprung von h${prev} auf h${level}:`, el.textContent);
  }
});

Sprung von h2 auf h4: Details (Beispiel)

Klick auf Überschrift kopiert Sprunglink

document.addEventListener('click', async (event) => {
  const heading = event.target.closest('h2[id], h3[id]');
  if (!(heading instanceof HTMLHeadingElement)) return;

  const url = `${location.origin}${location.pathname}#${heading.id}`;
  await navigator.clipboard.writeText(url);
  console.log('Link kopiert:', url);
});

Link kopiert: https://example.com/doku#installation

// Wichtig · Fallstricke

Alle sechs Ebenen verwenden dieselbe Schnittstelle. Die Ebene steckt nur im Tag-Namen. Ändern kann man sie nicht: Man muss ein neues Element anlegen und die Kinder übertragen, z. B. mit newEl.append(...old.childNodes); old.replaceWith(newEl).
tagName ist bei HTML-Dokumenten großgeschrieben ("H2"), localName kleingeschrieben ("h2"). Für Vergleiche ist localName robuster.
align ist veraltet. Stattdessen CSS verwenden.
Für Screenreader zählt die Überschriften-Struktur. Ebenen sollten nicht übersprungen werden. Die Ebene wählt man nach der Bedeutung, nicht nach der Schriftgröße. Den früher spezifizierten „Outline-Algorithmus“ für <section> hat nie ein Browser umgesetzt.
Text aus Nutzereingaben mit textContent setzen, nicht mit innerHTML, sonst droht XSS.
Browserunterstützung: seit jeher in allen Browsern verfügbar.

Siehe auch

Element HTMLHeadElement HTMLMediaElement HTMLAudioElement HTMLDetailsElement