Element.
Replaces an element in the document with other elements or text. The old element is removed from the page.
- Returns
undefined- Changes the original
- Yes
Example
#const buyButton = document.querySelector('#buy')
const badge = document.createElement('span')
badge.className = 'badge'
badge.textContent = 'Purchased ✓'
buyButton.replaceWith(badge)
console.log(buyButton.isConnected)
console.log(document.querySelector('.card').lastElementChild)
console.log(document.querySelector('#buy'))Definition and usage
#The replaceWith() method inserts the given nodes or strings in place of an element, and removes the element itself from the document. The new content lands exactly where the old element was: it gets the same parent and the same siblings.
It accepts any number of arguments, so you can replace one element with several. Strings are inserted as plain text, not as HTML, just like in append(). If you pass an element that’s already on the page, it gets moved to the new spot.
The replaced element doesn’t disappear from memory. As long as you hold a reference to it in a variable, you can restore it later, for example with another replaceWith() call. The older way to do the same thing is parent.replaceChild(new, old), which requires a reference to the parent and takes its arguments in a less intuitive order.
Syntax
#element.replaceWith(node1, node2, …)
element.replaceWith(text)Parameters
#node1…nodeN
elements or strings
Nodes or strings that will take the element’s place, in the given order.
More examples
#const status = document.querySelector('#status')
const points = document.createElement('strong')
points.textContent = '340 pts'
status.replaceWith('7 lessons complete, ', points)
const paragraph = document.querySelector('p')
console.log(paragraph.textContent)
console.log(paragraph.innerHTML)const title = document.querySelector('#title')
const input = document.createElement('input')
input.value = title.textContent
title.replaceWith(input)
console.log(document.querySelector('#title'))
input.value = 'A note about loops'
title.textContent = input.value
input.replaceWith(title)
console.log(document.querySelector('#title').textContent)After being replaced, the heading isn’t in the document, but the title variable still holds it. That’s why it returns to its spot with new text after the edit.
Browser support
#Widely available
Works in all modern browsers, phones included. You can use it without worry.
- Chrome
- Edge
- Firefox
- Safari
Good practices
#- You call
replaceWith()on the element that should disappear. You don’t need a reference to the parent, unlike withreplaceChild(). - Strings are inserted as text. If the new content should be HTML code, build elements with
createElement(), or insert the code withinsertAdjacentHTML()and only then remove the old element. - Keep a reference to the old element in a variable if you’ll need to restore it, for example after leaving edit mode.
Related entries
#- Element.remove()Removes an element from the document along with all of its content.
- Element.append()Adds elements or text at the end of an element’s content.
- document.createElement()Creates a new HTML element with the given tag name, ready to be inserted into the page.
- Node.cloneNode()Creates a copy of a node. With the argument true, it also copies all the content, meaning every element and text inside.
- Element.insertAdjacentHTML()Parses a string as HTML and inserts the resulting elements at a chosen position relative to an element.
Spotted a mistake or missing an example? Write to us.