Element.localName — Eigenschaft · JavaScript-Referenz

Signatur

Element.localName

Beschreibung

localName gibt den Namen eines Elements ohne Präfix zurück. Beim qualifizierten Namen svg:rect ist das z. B. "rect". Bei HTML-Elementen in einem HTML-Dokument ist der Wert immer kleingeschrieben, etwa "div" oder "button".

Damit unterscheidet sich localName von tagName bzw. nodeName: Diese geben bei HTML-Elementen den Namen in Großbuchstaben zurück ("DIV") und enthalten ein vorhandenes Präfix ("svg:rect"). Wer Elementtypen vergleichen will, ohne sich um die Groß-/Kleinschreibung zu kümmern, fährt mit localName meist besser.

Typische Einsatzfälle sind Event-Delegation (event.target.localName === "a"), das Durchlaufen gemischter HTML/SVG/MathML-Bäume, die Verarbeitung von XML-Dokumenten mit Namensräumen (zusammen mit namespaceURI) und Custom Elements: Dort liefert localName den registrierten Tag-Namen, z. B. "my-widget".

Rückgabewert

Typ

string

Beschreibung

Den lokalen Namen des Elements als String, ohne Namensraum-Präfix. Bei HTML-Elementen in HTML-Dokumenten kleingeschrieben, in XML-Dokumenten mit der Schreibweise aus dem Quelltext.

Beispiele

localName im Vergleich zu tagName

const div = document.createElement('div');
console.log(div.localName); // kleingeschrieben
console.log(div.tagName);   // großgeschrieben
console.log(div.nodeName);

div DIV DIV

Event-Delegation: nur Klicks auf Links oder Buttons behandeln

document.addEventListener('click', (event) => {
  const el = event.target;
  if (!(el instanceof Element)) return;

  switch (el.localName) {
    case 'a':
      console.log('Link geklickt:', el.getAttribute('href'));
      break;
    case 'button':
      console.log('Button geklickt:', el.textContent.trim());
      break;
  }
});

Link geklickt: /kontakt (bei Klick auf <a href="/kontakt">)

XML mit Namensraum-Präfix auswerten

const xml = `<root xmlns:geo="http://example.com/geo">
  <geo:point lat="52.52" lon="13.40"/>
</root>`;

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

console.log(point.localName);    // ohne Präfix
console.log(point.prefix);       // nur das Präfix
console.log(point.tagName);      // qualifizierter Name
console.log(point.namespaceURI);

point geo geo:point http://example.com/geo

Custom Elements und SVG im selben Baum erkennen

customElements.define('user-card', class extends HTMLElement {});

document.body.innerHTML = `
  <user-card></user-card>
  <svg><circle r="10"></circle></svg>
`;

for (const el of document.body.querySelectorAll('*')) {
  console.log(el.localName, '|', el.namespaceURI);
}

user-card | http://www.w3.org/1999/xhtml svg | http://www.w3.org/2000/svg circle | http://www.w3.org/2000/svg

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wie el.localName = 'span' wird ignoriert (im Strict Mode wirft sie einen TypeError). Um den Elementtyp zu ändern, legt man ein neues Element an und verschiebt die Kinder dorthin.
Groß-/Kleinschreibung: Nur in HTML-Dokumenten werden HTML-Elementnamen kleingeschrieben. In XML/XHTML-Dokumenten (application/xhtml+xml) und bei SVG-Elementen mit gemischter Schreibweise bleibt diese erhalten, z. B. "foreignObject" oder "linearGradient". Vergleiche mit toLowerCase() können hier also danebengehen.
Namensraum beachten: localName allein ist nicht eindeutig. Ein <a> in HTML und ein <a> in SVG haben beide "a". Für eine eindeutige Prüfung zusätzlich namespaceURI abfragen oder instanceof HTMLAnchorElement verwenden.
Historisch: Früher war localName auf Node definiert, dann wurde sie nach Element (und Attr) verschoben. Sehr alte Browser (Firefox vor 48, Chrome vor 46) lieferten bei anderen Knoten wie Textknoten null. Heute ist die Eigenschaft bei Nicht-Elementen undefined.

Siehe auch

Element.tagName Element.namespaceURI Element.prefix Node.nodeName Attr.localName Document.createElementNS() ElementInternals.ariaLive