</> programmierung.net
Start · Sprachen · JavaScript · Referenz · Element.insertAdjacentElement()

Element.insertAdjacentElement()

Methode

Fügt ein Element-Node an einer von vier Positionen relativ zum aufrufenden Element ein – davor, danach oder als erstes bzw. letztes Kind.

seit JavaScript Baseline: alle Browser (DOM Living Standard) Kategorie: webapi

Signatur

Element.prototype.insertAdjacentElement(position, element)

Beschreibung

insertAdjacentElement() fügt ein vorhandenes oder neu erzeugtes Element relativ zum Element ein, auf dem die Methode aufgerufen wird. Die Zielposition geben Sie mit einem von vier Schlüsselwörtern an: 'beforebegin', 'afterbegin', 'beforeend' oder 'afterend'.

  • 'beforebegin': direkt vor dem Element, als vorheriges Geschwisterelement
  • 'afterbegin': innerhalb des Elements, vor dem ersten Kind
  • 'beforeend': innerhalb des Elements, nach dem letzten Kind
  • 'afterend': direkt nach dem Element, als nächstes Geschwisterelement

Mit einer einzigen Methode decken Sie so die Fälle von before(), prepend(), append() und after() ab. Das ist praktisch, wenn die Position erst zur Laufzeit feststeht, etwa beim Drag & Drop oder beim Einfügen von Hinweisen direkt neben Formularfeldern. Anders als insertAdjacentHTML() parst die Methode kein HTML, sondern arbeitet mit echten DOM-Knoten. Dadurch bleiben Event-Listener und Referenzen erhalten, und es entsteht keine XSS-Gefahr.

Ist das übergebene Element schon im Dokument, wird es verschoben und nicht kopiert. Wenn Sie eine Kopie brauchen, nutzen Sie vorher element.cloneNode(true).

Parameter

Name Typ Default Beschreibung
$position Pflicht 'beforebegin' | 'afterbegin' | 'beforeend' | 'afterend' Position relativ zum aufrufenden Element. Groß- und Kleinschreibung spielt keine Rolle. Bei jedem anderen Wert wird ein SyntaxError (DOMException) geworfen.
$element Pflicht Element Das einzufügende Element. Ein bestehendes Element wird von seiner bisherigen Position verschoben. Andere Knotentypen (z. B. Text oder DocumentFragment) führen zu einem TypeError.

Rückgabewert

Typ
Element | null
Beschreibung
Das eingefügte Element. Schlägt das Einfügen fehl, gibt die Methode null zurück. Das passiert etwa bei 'beforebegin' oder 'afterend', wenn das Element keinen Elternknoten hat.

Beispiele

Fehlermeldung direkt hinter ein Eingabefeld setzen

const input = document.querySelector('#email');

const showError = (field, message) => {
  // Vorhandene Meldung entfernen
  field.nextElementSibling?.classList.contains('error') && field.nextElementSibling.remove();

  const error = document.createElement('span');
  error.className = 'error';
  error.textContent = message; // textContent statt innerHTML: sicher gegen XSS

  return field.insertAdjacentElement('afterend', error);
};

const el = showError(input, 'Bitte eine gültige E-Mail-Adresse eingeben.');
console.log(el.outerHTML);
<span class="error">Bitte eine gültige E-Mail-Adresse eingeben.</span>

Alle vier Positionen im Vergleich

// HTML: <div id="box"><p>Inhalt</p></div>
const box = document.querySelector('#box');
const make = (text) => Object.assign(document.createElement('em'), { textContent: text });

box.insertAdjacentElement('beforebegin', make('1'));
box.insertAdjacentElement('afterbegin', make('2'));
box.insertAdjacentElement('beforeend', make('3'));
box.insertAdjacentElement('afterend', make('4'));

console.log(box.parentElement.innerHTML);
<em>1</em><div id="box"><em>2</em><p>Inhalt</p><em>3</em></div><em>4</em>

Listeneintrag verschieben (Sortieren nach oben/unten)

// HTML: <ul><li>A</li><li>B</li><li>C</li></ul>
const moveItem = (item, direction) => {
  if (direction === 'up' && item.previousElementSibling) {
    item.previousElementSibling.insertAdjacentElement('beforebegin', item);
  } else if (direction === 'down' && item.nextElementSibling) {
    item.nextElementSibling.insertAdjacentElement('afterend', item);
  }
};

const [a] = document.querySelectorAll('li');
moveItem(a, 'down'); // A wird verschoben, nicht kopiert
console.log([...document.querySelectorAll('li')].map(li => li.textContent).join(','));
B,A,C

Rückgabewert null bei losgelöstem Element

const detached = document.createElement('div');
const child = document.createElement('span');

// Kein Elternknoten, deshalb ist 'afterend' nicht möglich
console.log(detached.insertAdjacentElement('afterend', child));

// Innerhalb des Elements funktioniert es
console.log(detached.insertAdjacentElement('beforeend', child) === child);
null true

// Wichtig · Fallstricke

  • Kein Parent, kein Geschwister: Hat das aufrufende Element keinen Elternknoten (z. B. frisch mit createElement() erzeugt) oder ist sein Elternknoten das Document, schlagen 'beforebegin' und 'afterend' fehl. Die Methode gibt dann null zurück und wirft keinen Fehler. Prüfen Sie den Rückgabewert, wenn das Ergebnis wichtig ist.
  • Verschieben statt Kopieren: Ein Element, das schon im DOM hängt, wird an seiner alten Stelle entfernt. Wenn Sie eine Kopie brauchen, nutzen Sie cloneNode(true). Beachten Sie aber, dass Event-Listener dabei nicht mitkopiert werden.
  • Nur Elemente: Für Text gibt es insertAdjacentText(), für HTML-Zeichenketten insertAdjacentHTML(). Mehrere Knoten oder ein DocumentFragment fügen Sie mit before(), after(), prepend() oder append() ein.
  • Ungültige Position: Tippfehler wie 'afterEnd ' mit Leerzeichen lösen einen SyntaxError aus. Die Groß- und Kleinschreibung ist dagegen egal.
  • Sicherheit: Im Gegensatz zu insertAdjacentHTML() wird nichts geparst. Solange Sie Inhalte über textContent setzen, ist die Methode unbedenklich gegenüber XSS.
  • Kompatibilität: Wird von allen modernen Browsern unterstützt, auch vom Internet Explorer ab Version 8 (dort nur eingeschränkt). Firefox unterstützt die Methode erst ab Version 48.

Siehe auch

Element.insertAdjacentHTML() Element.insertAdjacentText() Element.before() Element.after() Element.prepend() Element.append() Node.insertBefore() Document.createElement()
← Vorheriger Eintrag Element.innerHTML