Parent Element .replaceChild() / insertBefore()

// Replaces a child element with a new element.
parentElement.replaceChild(newElement, oldElement);

// Inserts an element immediately before the specified child element.
parentElement.insertBefore(newElement, referenceElement);

sample_replaceChild.html

<ul id="list">
	<li id="item1">Okabe Rintaro</li>
	<li id="item2">Makise Kurisu</li>
	<li id="item3">Shiina Mayuri</li>
</ul>
<ol id="steps">
	<li id="step1">Step 1</li>
	<li id="step2">Step 2</li>
	<li id="step3">Step 3</li>
</ol>

sample_replaceChild.js

var list = document.getElementById("list");

// Pattern 1: Replace a specific child element with replaceChild()
var newItem = document.createElement("li");
newItem.textContent = "Hashida Itaru";
var oldItem = document.getElementById("item2"); // Replace Makise Kurisu with Hashida Itaru.
var replaced = list.replaceChild(newItem, oldItem);
console.log(replaced.textContent); // Outputs 'Makise Kurisu'. (return value is the old element)

// Pattern 2: Prepend an element using insertBefore()
var insertItem = document.createElement("li");
insertItem.textContent = "Amane Suzuha (prepended)";
var item1 = document.getElementById("item1");
list.insertBefore(insertItem, item1); // Inserts immediately before item1.

// Pattern 3: Pass null as the second argument to append at the end
var lastItem = document.createElement("li");
lastItem.textContent = "Suzuha (appended at end)";
list.insertBefore(lastItem, null); // Same behavior as appendChild().

// Pattern 4: Move an existing element to a different position (not a copy — it's a move)
var steps = document.getElementById("steps");
var step1 = document.getElementById("step1");
steps.insertBefore(step1, null); // Moves Step 1 from the top to the end.

View sample page

Running the code above changes the HTML as follows.

<!-- Before -->
<ul id="list">
	<li id="item1">Item 1</li>
	<li id="item2">Item 2</li>
	<li id="item3">Item 3</li>
</ul>

<!-- After replaceChild() -->
<ul id="list">
	<li id="item1">Item 1</li>
	<li>New Item</li>
	<li id="item3">Item 3</li>
</ul>

<!-- After insertBefore() -->
<ul id="list">
	<li>Prepended Item</li>
	<li id="item1">Item 1</li>
	<li>New Item</li>
	<li id="item3">Item 3</li>
</ul>

parentElement.replaceChild() replaces an existing child element with a new element. The first argument is the new element, and the second argument is the existing child element to replace. The replaced old element is returned, so you can reuse it if needed.

parentElement.insertBefore() inserts an element immediately before a specified child element. Unlike parentElement.appendChild(), which can only append at the end, parentElement.insertBefore() lets you insert at any position. Passing null as the second argument appends the element at the end, making it equivalent to parentElement.appendChild().

If you pass an element that already exists in the DOM to either method, it is moved from its original position — not copied. If you need to place the same element in multiple locations, clone it first with element.cloneNode().