Element.insertAdjacentText() — Methode · JavaScript-Referenz

Signatur

Element.prototype.insertAdjacentText(where, data)

Beschreibung

insertAdjacentText() erzeugt aus einem String einen neuen Textknoten und fügt ihn an einer von vier Positionen relativ zum aufrufenden Element ein: vor dem Element, als erstes Kind, als letztes Kind oder nach dem Element. Der String wird dabei nie als HTML interpretiert. Zeichen wie < oder & erscheinen also genau so im Dokument, wie sie im String stehen.

Die Methode passt gut, wenn du Text an vorhandene Inhalte anhängen oder voranstellen willst, ohne das ganze Element neu zu rendern. Bei textContent += ... würden alle Kindknoten ersetzt, samt Event-Listenern und Zustand. Bei insertAdjacentText() bleiben die vorhandenen Knoten dagegen unangetastet.

Die Methode gehört zu einer Familie mit insertAdjacentHTML() (fügt geparstes HTML ein) und insertAdjacentElement() (fügt einen vorhandenen Elementknoten ein). Weil keine Nutzereingabe als Markup geparst wird, ist insertAdjacentText() die sichere Wahl für Texte aus unsicheren Quellen.

Die Positionen im Überblick (für <p id="ziel">Inhalt</p>):

"beforebegin": vor dem Element selbst, als vorheriger Geschwisterknoten
"afterbegin": im Element, vor dem ersten Kind
"beforeend": im Element, nach dem letzten Kind
"afterend": nach dem Element selbst, als nächster Geschwisterknoten

Parameter

Name	Typ	Default	Beschreibung
$where Pflicht	"beforebegin" \| "afterbegin" \| "beforeend" \| "afterend"		Position relativ zum Element. Groß- und Kleinschreibung spielt keine Rolle. Ungültige Werte lösen einen `SyntaxError` (`DOMException`) aus.
$data Pflicht	string		Der Text für den neuen Textknoten. Andere Werte werden in einen String umgewandelt (z. B. `42` → `"42"`). HTML wird nicht geparst.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined). Wer eine Referenz auf den eingefügten Knoten braucht, erzeugt ihn selbst mit document.createTextNode() und fügt ihn z. B. mit before()/append() ein.

Beispiele

Alle vier Positionen im Vergleich

// HTML: <div id="box"><strong>Mitte</strong></div>
const box = document.querySelector('#box');

box.insertAdjacentText('beforebegin', '[vor] ');
box.insertAdjacentText('afterbegin', '[Anfang] ');
box.insertAdjacentText('beforeend', ' [Ende]');
box.insertAdjacentText('afterend', ' [nach]');

console.log(box.parentElement.innerHTML.trim());

[vor] <div id="box">[Anfang] <strong>Mitte</strong> [Ende]</div> [nach]

Nutzereingabe sicher anhängen (kein XSS)

// HTML: <p id="gruss">Hallo, </p> <input id="name">
const gruss = document.querySelector('#gruss');
const eingabe = '<img src=x onerror="alert(1)">';

// Wird als reiner Text eingefügt, nicht als HTML ausgeführt
gruss.insertAdjacentText('beforeend', eingabe);

console.log(gruss.textContent);
console.log(gruss.querySelector('img'));

Hallo, <img src=x onerror="alert(1)"> null

Log-Ausgabe erweitern, ohne Listener zu verlieren

// HTML: <pre id="log"><button id="clear">Leeren</button>
</pre>
const log = document.querySelector('#log');
document.querySelector('#clear').addEventListener('click', () => {
  log.querySelectorAll(':scope > :not(button)').forEach(n => n.remove());
});

const schreibe = (msg) => {
  const zeit = new Date().toLocaleTimeString('de-DE');
  // textContent += ... würde den Button samt Listener zerstören
  log.insertAdjacentText('beforeend', `${zeit} ${msg}\n`);
};

schreibe('Anwendung gestartet');
schreibe('Daten geladen');
console.log(log.childNodes.length);

4

Fehlerbehandlung bei ungültiger Position und fehlendem Elternknoten

const span = document.createElement('span');

try {
  span.insertAdjacentText('mitte', 'x');
} catch (e) {
  console.log(e.name);
}

// Losgelöstes Element ohne Elternknoten: beforebegin/afterend bewirken nichts
span.insertAdjacentText('afterend', 'verloren');
span.insertAdjacentText('beforeend', 'drin');
console.log(span.outerHTML);

SyntaxError <span>drin</span>

// Wichtig · Fallstricke

Keine Rückgabe: Die Methode gibt den erzeugten Textknoten nicht zurück. Brauchst du ihn später, erzeuge ihn mit document.createTextNode() und füge ihn mit insertAdjacentElement() ist nicht möglich – nutze stattdessen before(), prepend(), append() oder after().
Ohne Elternknoten: "beforebegin" und "afterend" brauchen einen Elternknoten. Fehlt er (losgelöstes Element) oder ist er das Document (z. B. bei document.documentElement), passiert nichts und es gibt keinen Fehler.
Ungültige Position: Andere Werte als die vier Schlüsselwörter lösen einen SyntaxError aus.
Sicherheit: Der Text wird nicht als HTML geparst. Damit ist die Methode für Nutzereingaben so sicher wie textContent, anders als insertAdjacentHTML() oder innerHTML, die ohne Bereinigung XSS ermöglichen.
Benachbarte Textknoten: Mehrere Aufrufe erzeugen mehrere einzelne Textknoten nebeneinander. Mit element.normalize() lassen sie sich bei Bedarf zusammenführen.
Kompatibilität: Wird von allen modernen Browsern unterstützt (Firefox erst ab Version 48). Alternativ gibt es die neueren Methoden before()/after()/prepend()/append(), die Strings ebenfalls als Text einfügen und mehrere Argumente annehmen.

Siehe auch

Element.insertAdjacentHTML() Element.insertAdjacentElement() Element.append() Element.before() Node.textContent Document.createTextNode() Node.normalize()