Node.replaceChild() — Methode · JavaScript-Referenz

Signatur

Node.prototype.replaceChild(newChild, oldChild)

Beschreibung

replaceChild() wird auf dem Elternknoten aufgerufen und tauscht einen seiner direkten Kindknoten gegen einen anderen Knoten aus. Der neue Knoten kommt genau an die Stelle des alten. Der alte Knoten wird aus dem Dokument entfernt, bleibt aber als Objekt erhalten und wird zurückgegeben. Man kann ihn also später wieder einfügen.

Ist newChild schon irgendwo im Dokument eingehängt, wird er dort zuerst entfernt und dann verschoben. Er wird also nicht kopiert. Wer eine Kopie braucht, verwendet vorher newChild.cloneNode(true). Ist newChild ein DocumentFragment, werden alle Kinder des Fragments in ihrer Reihenfolge an der Stelle von oldChild eingefügt. Das Fragment ist danach leer.

Typische Einsatzfälle sind der Austausch von Platzhaltern gegen fertig gerenderte Inhalte (z. B. Lade-Spinner gegen Daten), das Umschalten zwischen Ansichten und das Ersetzen von Textknoten. Für neuen Code ist oft oldChild.replaceWith(...nodes) bequemer: Es wird auf dem zu ersetzenden Knoten selbst aufgerufen, nimmt mehrere Knoten oder Strings an und braucht keinen Verweis auf das Elternelement.

Beachte die Reihenfolge der Argumente: zuerst der neue, dann der alte Knoten. Das wird leicht verwechselt.

Parameter

Name	Typ	Default	Beschreibung
$newChild Pflicht	Node		Der neue Knoten, der an die Stelle von `oldChild` tritt. Ist er bereits im DOM, wird er verschoben. Ein `DocumentFragment` fügt alle seine Kinder ein.
$oldChild Pflicht	Node		Der bestehende direkte Kindknoten des Elternknotens, der ersetzt werden soll.

Rückgabewert

Typ

Node

Beschreibung

Der ersetzte Knoten, also oldChild. Er ist nun aus dem Dokument entfernt, kann aber erneut eingefügt werden.

Beispiele

Platzhalter durch geladenen Inhalt ersetzen

// HTML: <div id="container"><p id="loading">Lade Daten …</p></div>
const container = document.getElementById('container');
const loading = document.getElementById('loading');

const loadUsers = async () => {
  const response = await fetch('https://jsonplaceholder.typicode.com/users');
  const users = await response.json();

  const list = document.createElement('ul');
  for (const user of users) {
    const li = document.createElement('li');
    li.textContent = user.name;
    list.append(li);
  }

  const removed = container.replaceChild(list, loading);
  console.log(`Entfernt: ${removed.id}`);
};

loadUsers();

Entfernt: loading

Überschrift-Ebene austauschen (h2 → h3), Inhalt übernehmen

// HTML: <article><h2 id="title">Kapitel <em>1</em></h2></article>
const oldHeading = document.getElementById('title');
const newHeading = document.createElement('h3');

// Kindknoten und Attribute übernehmen
newHeading.append(...oldHeading.childNodes);
newHeading.id = oldHeading.id;

oldHeading.parentNode.replaceChild(newHeading, oldHeading);
console.log(document.querySelector('article').innerHTML);

<h3 id="title">Kapitel <em>1</em></h3>

Knoten tauschen und den alten wiederverwenden

// HTML: <div id="view"><section id="a">Ansicht A</section></div>
const view = document.getElementById('view');
const viewB = document.createElement('section');
viewB.id = 'b';
viewB.textContent = 'Ansicht B';

let current = document.getElementById('a');
let stored = viewB;

const toggle = () => {
  // replaceChild gibt den alten Knoten zurück, den wir für später aufheben
  const removed = view.replaceChild(stored, current);
  [current, stored] = [stored, removed];
  console.log(`Aktiv: ${current.id}`);
};

toggle();
toggle();

Aktiv: b Aktiv: a

Mehrere Knoten per DocumentFragment einsetzen

// HTML: <ul id="menu"><li id="slot">…</li></ul>
const menu = document.getElementById('menu');
const slot = document.getElementById('slot');

const fragment = document.createDocumentFragment();
for (const label of ['Start', 'Blog', 'Kontakt']) {
  const li = document.createElement('li');
  li.textContent = label;
  fragment.append(li);
}

menu.replaceChild(fragment, slot);
console.log(menu.children.length);

3

// Wichtig · Fallstricke

Reihenfolge der Argumente: replaceChild(neu, alt). Sind die Argumente vertauscht, gibt es meist einen NotFoundError, weil der neue Knoten noch kein Kind des Elternknotens ist.
Nur direkte Kinder: Ist oldChild kein direktes Kind des Elternknotens, wird eine DOMException (NotFoundError) ausgelöst. Am sichersten ist oldChild.parentNode.replaceChild(neu, oldChild).
HierarchyRequestError: Diese Ausnahme kommt, wenn newChild ein Vorfahre des Elternknotens ist, wenn der Knotentyp an dieser Stelle nicht erlaubt ist (z. B. ein zweites Wurzelelement im Document) oder wenn ein Text-Knoten direkt unter Document landen würde.
Verschieben statt Kopieren: Ein bereits eingehängter newChild verschwindet von seiner alten Position. Für eine Kopie cloneNode(true) verwenden. Achtung: Event-Listener werden dabei nicht mitkopiert.
Zustand geht verloren: Der alte Knoten verliert mit dem Entfernen z. B. den Fokus. Bei <iframe>-Elementen wird der Inhalt beim Wiedereinfügen neu geladen.
Sicherheit: Neue Knoten mit createElement und textContent erzeugen, nicht mit innerHTML aus ungeprüften Daten. So vermeidest du XSS.
Kompatibilität: Wird in allen Browsern unterstützt. Die modernere Alternative Element.replaceWith() gibt es in allen aktuellen Browsern, aber nicht im Internet Explorer.

Siehe auch

Node.removeChild() Node.appendChild() Node.cloneNode() Node.contains() Node.isSameNode()