The Document
object's importNode()
method creates a copy of a Node
or DocumentFragment
from another document, to be inserted into the current document later.
The imported node is not yet included in the document tree. To include it, you need to call an insertion method such as appendChild()
or insertBefore()
with a node that is currently in the document tree.
Unlike document.adoptNode()
, the original node is not removed from its original document. The imported node is a clone of the original.
Syntax
const importedNode = document.importNode(externalNode [, deep]);
Parameters
externalNode
- The external
Node
orDocumentFragment
to import into the current document. deep
Optional- A Boolean which controls whether to include the entire DOM subtree of the
externalNode
in the import.- If
deep
is set totrue
, thenexternalNode
and all of its descendants are copied. - If
deep
is set tofalse
, then onlyexternalNode
is imported — the new node has no children.
Note: In the DOM4 specification,
deep
was an optional argument with a default value oftrue
.This default has changed in the latest spec! The new default value is
false
.Best Practice: Though it's still an optional argument, you should always provide the
deep
argument for backward and forward compatibility.- With Gecko 28.0 (Firefox 28 / Thunderbird 28 / SeaMonkey 2.25 / Firefox OS 1.3), the console warns developers not to omit the argument.
- Starting with Gecko 29.0 (Firefox 29 / Thunderbird 29 / SeaMonkey 2.26)), a shallow clone is defaulted instead of a deep clone.
- If
Return value
The copied importedNode
in the scope of the importing document.
Note: importedNode
's Node.parentNode
is null
, since it has not yet been inserted into the document tree!
Example
const iframe = document.querySelector("iframe"); const oldNode = iframe.contentWindow.document.getElementById("myNode"); const newNode = document.importNode(oldNode, true); document.getElementById("container").appendChild(newNode);
Notes
Before they can be inserted into the current document, nodes from external documents should either be:
- cloned using
document.importNode()
; or - adopted using
document.adoptNode()
.
Best Practice: Although Firefox doesn't currently enforce this rule, we encourage you to follow this rule for improved future compatibility.
For more on the Node.ownerDocument
issues, see the W3C DOM FAQ.
Specifications
Specification | Status | Comment |
---|---|---|
DOM The definition of 'document.importNode()' in that specification. |
Living Standard | |
Document Object Model (DOM) Level 2 Core Specification The definition of 'document.importNode()' in that specification. |
Obsolete | Initial definition |
Browser compatibility
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
importNode | Chrome Full support 1 | Edge Full support 12 | Firefox Full support 4 | IE Full support 9 | Opera Full support 9 | Safari Full support Yes | WebView Android Full support Yes | Chrome Android Full support Yes | Firefox Android Full support 4 | Opera Android Full support 10.1 | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
deep parameter optional | Chrome Full support Yes | Edge Full support ≤18 | Firefox Full support 10 | IE No support No | Opera Full support Yes | Safari Full support Yes | WebView Android Full support Yes | Chrome Android Full support Yes | Firefox Android Full support 10 | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
Legend
- Full support
- Full support
- No support
- No support
See also
document.adoptNode()
, which behaves very similar to this methodNode.appendChild()
Node.insertBefore()