JavaScript Document adoptNode() Method

What You’ll Learn

document.adoptNode() is an instance method that moves a node from another document into the current one. Learn how ownerDocument changes, why parentNode is null until you insert, MDN’s iframe example, and how adoptNode differs from importNode and cloneNode.

Introduction

Every DOM node belongs to a Document through ownerDocument. When you build nodes in an iframe, a detached Document, or parsed HTML, those nodes live in a different document than your main page.

MDN: Document.adoptNode(externalNode) transfers a node from another document into the method’s document. The adopted node and its subtree are removed from their original document, and ownerDocument changes to the current document. You can then insert it with appendChild().

Related tutorials: ownerDocument, cloneNode(), appendChild(), Document constructor.

Understanding document.adoptNode()

An instance method on the live page’s document object.

• Parameter — externalNode: a node from another document (MDN).
• Returns — the adopted node (same object as externalNode after the call) (MDN).
• Removes from source — node and subtree leave the original document (MDN).
• Updates owner — ownerDocument becomes the current document (MDN).
• parentNode is null — until you insert into the tree (MDN).
• Alternative — importNode() copies without removing from source (MDN).

📝 Syntax

document.adoptNode(externalNode)

Parameters

• externalNode — the node from another document to adopt (MDN).

Return value

The adopted node in the scope of the importing document (MDN).

Common pattern

const otherDoc = new Document();
const p = otherDoc.createElement("p");
p.textContent = "From another document";

const adopted = document.adoptNode(p);
// adopted === p (same object)
// adopted.ownerDocument === document
// adopted.parentNode === null

document.getElementById("host").appendChild(adopted);

⚖️ adoptNode vs importNode vs appendChild

Examples Gallery

Examples follow MDN Document: adoptNode(). Adopt first, then insert with appendChild.

const otherDoc = new Document();
const p = otherDoc.createElement("p");
p.textContent = "Adopted paragraph";

const adopted = document.adoptNode(p);
document.getElementById("host").appendChild(adopted);

console.log(adopted.textContent); // "Adopted paragraph"

Adopted paragraph

const iframe = document.querySelector("iframe");
const iframeImages = iframe.contentDocument.querySelectorAll("img");
const newParent = document.getElementById("images");

iframeImages.forEach((imgEl) => {
  newParent.appendChild(document.adoptNode(imgEl));
});

Images moved to #images (iframe now empty)

const otherDoc = new Document();
const span = otherDoc.createElement("span");
span.textContent = "Hi";

console.log(span.ownerDocument === otherDoc); // true

const adopted = document.adoptNode(span);
console.log(adopted.ownerDocument === document); // true

true
true

const otherDoc = new Document();
const div = otherDoc.createElement("div");

const adopted = document.adoptNode(div);
console.log(adopted.parentNode); // null (MDN)

const host = document.getElementById("host");
host.appendChild(adopted);
console.log(adopted.parentNode === host); // true

null
true

const otherDoc = new Document();
const li = otherDoc.createElement("li");
li.textContent = "Item";
otherDoc.body.appendChild(li);

const adopted = document.adoptNode(li);

console.log({
  adoptedSameRef: adopted === li,
  stillInOtherDoc: otherDoc.body.contains(li) // false — moved
});

{ adoptedSameRef: true, stillInOtherDoc: false }

🚀 Common Use Cases

• Iframe content — move nodes from iframe.contentDocument (MDN example).
• Parsed Documents — adopt nodes from parseHTML() / DOMParser output.
• Detached Documents — move nodes built with new Document().
• Widget reparenting — transfer a subtree without cloning event listeners on a new object.
• Not for same-document moves — use appendChild directly when ownerDocument already matches.
• When you need a copy — prefer importNode or cloneNode.

📝 Notes

• MDN: Baseline Widely available since July 2015.
• Not Deprecated, Experimental, or Non-standard.
• Return value and externalNode are the same object after adoption (MDN).
• Adopt or importNode before inserting foreign nodes (MDN Notes).
• For same-document reparenting, appendChild alone is enough.
• Related: ownerDocument, appendChild(), cloneNode(), parseHTML().

💡 Best Practices