HTMLElement — Schnittstelle · JavaScript-Referenz

Signatur

interface HTMLElement extends Element

Beschreibung

HTMLElement ist die gemeinsame Basis-Schnittstelle aller HTML-Elemente im DOM. Die Vererbungskette lautet EventTarget → Node → Element → HTMLElement. Spezialisierte Schnittstellen wie HTMLInputElement, HTMLDivElement oder HTMLAnchorElement erweitern sie. Elemente ohne eigenes Interface (z. B. <section>, <nav>, <b>) sind direkte Instanzen von HTMLElement.

Wichtige Eigenschaften und Methoden, die hier definiert sind:

Inhalt & Darstellung: innerText, outerText, hidden, style, title, lang, dir, translate
Daten: dataset (Zugriff auf data-*-Attribute als DOMStringMap)
Interaktion: click(), focus(), blur(), tabIndex, accessKey, contentEditable, isContentEditable, draggable, inert
Layout: offsetWidth, offsetHeight, offsetTop, offsetLeft, offsetParent
Popover-API: popover, showPopover(), hidePopover(), togglePopover()
Custom Elements: attachInternals()

Zusätzlich implementiert HTMLElement die Event-Handler-Eigenschaften (onclick, oninput usw.) über GlobalEventHandlers. Die Schnittstelle besitzt keinen direkt aufrufbaren Konstruktor – Instanzen entstehen über document.createElement(), per HTML-Parser oder als Basisklasse für eigene Custom Elements via class X extends HTMLElement.

Rückgabewert

Typ

HTMLElement

Beschreibung

Keine Funktion – Instanzen erhält man z. B. über document.createElement(), document.querySelector() oder document.body.

Beispiele

Element erzeugen und HTMLElement-Eigenschaften nutzen

const box = document.createElement('section');
box.title = 'Hinweis';
box.lang = 'de';
box.dataset.userId = '42'; // wird zu data-user-id="42"
box.style.padding = '1rem';
box.innerText = 'Willkommen zurück!';
document.body.append(box);

console.log(box instanceof HTMLElement);
console.log(box.outerHTML);

true <section title="Hinweis" lang="de" data-user-id="42" style="padding: 1rem;">Willkommen zurück!</section>

Sichtbarkeit, Fokus und Klick steuern

const dialog = document.querySelector('#hilfe');
const button = document.querySelector('#hilfe-button');

button.addEventListener('click', () => {
  dialog.hidden = !dialog.hidden;
  if (!dialog.hidden) {
    dialog.tabIndex = -1; // programmatisch fokussierbar machen
    dialog.focus();
  }
});

// Klick programmatisch auslösen
button.click();
console.log(dialog.hidden, document.activeElement === dialog);

false true

Eigenes Custom Element von HTMLElement ableiten

class UserBadge extends HTMLElement {
  static observedAttributes = ['name'];

  connectedCallback() {
    this.render();
  }

  attributeChangedCallback() {
    this.render();
  }

  render() {
    this.textContent = `👤 ${this.getAttribute('name') ?? 'Gast'}`;
  }
}

customElements.define('user-badge', UserBadge);

const badge = document.createElement('user-badge');
badge.setAttribute('name', 'Anna');
document.body.append(badge);
console.log(badge.textContent);

👤 Anna

Layout-Maße auslesen

const header = document.querySelector('header');
const { offsetWidth, offsetHeight, offsetTop } = header;
console.log(`Header: ${offsetWidth}×${offsetHeight}px, Abstand oben: ${offsetTop}px`);

Header: 1280×64px, Abstand oben: 0px

// Wichtig · Fallstricke

Kein Konstruktor: new HTMLElement() wirft einen TypeError („Illegal constructor“). Nur in Unterklassen, die per customElements.define() registriert wurden, ist super() erlaubt.
innerText vs. textContent: innerText berücksichtigt CSS (versteckter Text fehlt) und löst dadurch ein Reflow aus – bei vielen Zugriffen langsam. Für reinen Text ist textContent (aus Node) schneller.
Layout-Thrashing: offsetWidth/offsetHeight erzwingen eine synchrone Layout-Berechnung. Lese- und Schreibzugriffe in Schleifen nicht abwechseln.
hidden und CSS: Eine CSS-Regel wie display: flex überschreibt das hidden-Attribut. Ggf. [hidden] { display: none !important; } ergänzen. Der Wert hidden="until-found" wird noch nicht von allen Browsern unterstützt.
dataset-Namen: data-user-id wird zu dataset.userId (camelCase); Werte sind immer Strings.
SVG/MathML: SVG-Elemente sind SVGElement, keine HTMLElement-Instanzen – instanceof HTMLElement ist dort false. Gemeinsame Eigenschaften wie dataset, style, focus() stammen aus Mixins und sind trotzdem vorhanden.
Kompatibilität: Kern-Eigenschaften funktionieren in allen Browsern. Neuere Teile wie popover/showPopover() (Baseline 2024), inert (Baseline 2023) und attachInternals() vor der Nutzung prüfen.
Sicherheit: Für Benutzereingaben innerText/textContent statt innerHTML verwenden, um XSS zu vermeiden.

Siehe auch

Element Node HTMLBRElement HTMLHRElement HTMLLIElement