Element.replaceChildren() — Methode · JavaScript-Referenz

Signatur

Element.prototype.replaceChildren(...nodes)

Beschreibung

Die Methode replaceChildren() entfernt in einem Schritt alle bisherigen Kindknoten eines Elements und fügt danach die übergebenen Knoten in der angegebenen Reihenfolge ein. Das sind Elemente, Textknoten und Kommentare. Übergebene Zeichenketten werden automatisch in Text-Knoten umgewandelt und nicht als HTML ausgewertet.

Typische Einsatzfälle sind das Leeren eines Containers (Aufruf ohne Argumente), das Neuaufbauen einer Liste nach dem Filtern oder Sortieren und das Verschieben von Knoten zwischen zwei Containern. Die Methode ist eine sichere und gut lesbare Alternative zu element.innerHTML = '' oder zu Schleifen mit removeChild().

Gehört ein übergebener Knoten schon zu einem anderen Elternknoten, wird er dort entfernt und hierher verschoben. Er wird also nicht kopiert. Ein DocumentFragment wird „ausgepackt“: Nur seine Kinder werden eingefügt, und das Fragment ist danach leer.

Die Methode gibt es auch auf Document und DocumentFragment, da sie aus dem Mixin ParentNode stammt.

Parameter

Name	Typ	Default	Beschreibung
$...nodes	Node \| string		Beliebig viele Knoten oder Zeichenketten, die die bisherigen Kinder ersetzen. Zeichenketten werden zu `Text`-Knoten. Ohne Argumente wird das Element geleert.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert.

Beispiele

Container vollständig leeren

const liste = document.querySelector('#ergebnisse');
console.log(liste.childNodes.length); // z. B. 12

// Aufruf ohne Argumente entfernt alle Kinder
liste.replaceChildren();
console.log(liste.childNodes.length);

12 0

Gefilterte Liste neu aufbauen

const produkte = [
  { name: 'Tastatur', preis: 49 },
  { name: 'Maus', preis: 19 },
  { name: 'Monitor', preis: 199 }
];

const ul = document.querySelector('#produkte');

const render = (maxPreis) => {
  const items = produkte
    .filter((p) => p.preis <= maxPreis)
    .map((p) => {
      const li = document.createElement('li');
      li.textContent = `${p.name} – ${p.preis} €`;
      return li;
    });
  // Alte Einträge weg, neue rein – in einem Aufruf
  ul.replaceChildren(...items);
};

render(50);
console.log(ul.children.length);

2

Knoten zwischen zwei Listen verschieben

const verfuegbar = document.querySelector('#verfuegbar');
const ausgewaehlt = document.querySelector('#ausgewaehlt');

// Alle ausgewählten Optionen zurück nach "verfügbar" verschieben
verfuegbar.replaceChildren(
  ...verfuegbar.children,
  ...ausgewaehlt.children
);

// Die Knoten wurden verschoben, nicht kopiert
console.log(ausgewaehlt.children.length);

Text und Elemente mischen – sicher gegen XSS

const status = document.querySelector('#status');
const benutzername = '<img src=x onerror=alert(1)>';

const fett = document.createElement('strong');
fett.textContent = benutzername;

// Zeichenketten werden als Text eingefügt, nicht als HTML
status.replaceChildren('Angemeldet als ', fett, '.');
console.log(status.innerHTML);

Angemeldet als <strong><img src=x onerror=alert(1)></strong>.

// Wichtig · Fallstricke

Browser-Kompatibilität: Wird ab Chrome/Edge 86, Firefox 78 und Safari 14 unterstützt. Der Internet Explorer kennt die Methode nicht. Als Ersatz dient dort while (el.firstChild) el.removeChild(el.firstChild) mit anschließendem append().
Verschieben statt Kopieren: Knoten, die schon woanders im DOM hängen, werden dort entfernt. Wenn eine Kopie gewünscht ist, vorher node.cloneNode(true) aufrufen.
Live-Collections: el.children ist eine live-Collection. Mit dem Spread-Operator (...el.children) wird sie vor dem Aufruf in ein festes Array kopiert. Deshalb funktioniert das Verschiebe-Beispiel zuverlässig.
Fehler: Ist die neue Knotenstruktur ungültig, wird eine HierarchyRequestError-DOMException geworfen. Das passiert zum Beispiel, wenn ein Vorfahre des Elements eingefügt werden soll oder wenn ein Document zwei Wurzelelemente bekommen würde. In diesem Fall bleiben die alten Kinder erhalten.
Sicherheit: Anders als bei innerHTML wird kein HTML ausgewertet. Die Methode ist daher gut geeignet, um Benutzereingaben sicher darzustellen.
Ereignis-Listener und Zustand: Beim Entfernen gehen Formularzustände der alten Kinder verloren, sofern keine Referenz auf die Knoten mehr besteht. Listener hängen am Knoten selbst und bleiben bei verschobenen Knoten erhalten.

Siehe auch

Element.append() Element.prepend() Element.replaceWith() Node.replaceChild() Node.removeChild() Element.innerHTML DocumentFragment