JavaScript replaceChild() Method

The JavaScript replaceChild() method replaces an existing child node with a new node inside a parent element. It is part of the DOM API and is commonly used to update page content dynamically without rebuilding the entire parent element.

JavaScript replaceChild() Method Syntax

The syntax of the replaceChild() method is:

parentNode.replaceChild(newChild, oldChild);

Parameters:

• newChild: The node that will be inserted into the parent.
• oldChild: The existing child node that will be replaced.

Return value: The method returns the replaced child node, which is the former oldChild.

Basic Example of JavaScript replaceChild()

In this example, the replaceChild() method replaces an existing paragraph with a new paragraph.

<div id="container">
    <p id="oldText">This is the old paragraph.</p>
</div>

<script>
const container = document.getElementById("container");

const newParagraph = document.createElement("p");
newParagraph.textContent = "This is the new paragraph.";

const oldParagraph = document.getElementById("oldText");

container.replaceChild(newParagraph, oldParagraph);
</script>

Resulting HTML:

<div id="container">
    <p>This is the new paragraph.</p>
</div>

The old paragraph is removed and the new paragraph takes its place.

JavaScript replaceChild() with an HTML Element

You can replace one type of HTML element with another. The following example replaces a heading with a paragraph.

<div id="content">
    <h2 id="heading">Original Heading</h2>
</div>

<script>
const content = document.getElementById("content");
const heading = document.getElementById("heading");

const paragraph = document.createElement("p");
paragraph.textContent = "The heading has been replaced.";

content.replaceChild(paragraph, heading);
</script>

After execution, the h2 element is replaced by a p element.

JavaScript replaceChild() with Text Nodes

The replaceChild() method can also replace a text node. Use document.createTextNode() to create the replacement text.

<div id="message">Old message</div>

<script>
const message = document.getElementById("message");
const oldText = message.firstChild;

const newText = document.createTextNode("Updated message");

message.replaceChild(newText, oldText);
</script>

The text inside the div is changed from “Old message” to “Updated message”.

JavaScript replaceChild() Return Value

The replaceChild() method returns the node that was removed from the parent. You can store this returned node in a variable and use it later.

<div id="container">
    <p id="old">Old content</p>
</div>

<script>
const container = document.getElementById("container");
const oldElement = document.getElementById("old");

const newElement = document.createElement("p");
newElement.textContent = "New content";

const removedElement = container.replaceChild(
    newElement,
    oldElement
);

console.log(removedElement.textContent);
</script>

Output:

Old content

JavaScript replaceChild() with Existing Elements

If the new node already exists elsewhere in the document, replaceChild() moves it from its current location and places it where the old child was. The node is moved, not copied.

<div id="first">
    <p id="moving">Move this paragraph</p>
</div>

<div id="second">
    <p id="target">Replace this paragraph</p>
</div>

<script>
const second = document.getElementById("second");
const moving = document.getElementById("moving");
const target = document.getElementById("target");

second.replaceChild(moving, target);
</script>

The paragraph with the ID moving is moved into the second container and takes the place of the paragraph with the ID target.

JavaScript replaceChild() in a List

The method can replace an item in a list while preserving the other list items.

<ul id="languages">
    <li>HTML</li>
    <li id="oldLanguage">Old Language</li>
    <li>CSS</li>
</ul>

<script>
const languages = document.getElementById("languages");
const oldLanguage = document.getElementById("oldLanguage");

const newLanguage = document.createElement("li");
newLanguage.textContent = "JavaScript";

languages.replaceChild(newLanguage, oldLanguage);
</script>

The second list item becomes “JavaScript”, while the HTML and CSS items remain unchanged.

JavaScript replaceChild() vs replaceWith()

Both methods can replace an element, but their syntax and behavior are different.

Example using replaceWith():

const oldElement = document.getElementById("oldElement");

const newElement = document.createElement("p");
newElement.textContent = "Replacement content";

oldElement.replaceWith(newElement);

Common Errors When Using replaceChild()

• Wrong parent node: The old child must belong to the parent on which replaceChild() is called. Otherwise, the browser throws a NotFoundError.
• Invalid node: The first argument must be a valid Node object, not an ordinary HTML string.
• Incorrect argument order: Pass the new node first and the old node second.
• Missing element: Check that DOM elements exist before calling the method, especially when scripts run before the HTML has loaded.

You can check that both nodes exist before replacing an element:

const parent = document.getElementById("container");
const oldChild = document.getElementById("oldChild");

if (parent && oldChild) {
    const newChild = document.createElement("p");
    newChild.textContent = "Updated content";

    parent.replaceChild(newChild, oldChild);
}

Browser Support for JavaScript replaceChild()

The replaceChild() method is a long-established DOM API and is supported by all modern major browsers, including Chrome, Firefox, Safari, and Edge. It is also available in many older browser versions.