Arguments

node (Node) required

The node to import.

deep (Boolean) required

If true then the subtree underneath the specified node is also imported; if false then only the node itself is imported.

For Attr and EntityReference nodes this argument is ignored (see notes above). For Text, CDATASection, Comment, ProcessingInstruction and Notation nodes this argument is redundant because these types of node cannot have children.

Description

Imports a node from another document into this one, optionally including all its children. The imported node is owned by the importing document (ownerDocument is equal to document), and has no parent until it's attached.

The imported node can then be added to the document using Node methods such as appendChild or insertBefore.

The original node is not altered or removed from the document it came from — this method creates a copy of the node in this document. The new node has the same nodeName and nodeType as the original node, as well as any namespace information (prefix, localName and namespaceURI) if applicable.

Additional information is also copied as appropriate so that the new node mirrors the properties of the same type of node in this document (for example, if the node is an Element it will now have any default attributes that apply to that element in this document type).

Here are the specifics of behavior for each type of node:

Attr

The ownerElement is null and the specified property is true. The descendants of the attribute are imported recursively to form the same subtree as the original. The deep argument has no effect on attribute nodes — their children are always included when importing.

CDATASection

Comment

Text

These nodes are imported along with their data and length properties; the deep argument has no effect because these types of node cannot have children.

DocumentFragment

If the deep argument is true then the document fragment's subtree is imported intact; otherwise an empty DocumentFragment node is created.

Document

DocumentType

These types of node cannot be imported.

Element

Explicitly defined attributes are imported along with the element. Attributes which are not defined but have a default value in the original document are not included, but attributes which have a default value in this document are created and assigned to the imported element. If the deep argument is true then the element's subtree is also imported.

Entity

Although Entity nodes can be imported, they cannot be assigned to this document type, because DocumentType nodes are readonly. All properties of the original entity are imported (publicId, systemId and notationName); if the deep parameter is true then the subtree is also imported.

EntityReference

Only the entity reference itself is imported — its descendants are never included, even if the deep argument is true, because the original document and this document may defined the entity differently. If this document type has a definition for this entity name, its value is assigned.

Notation

Although Notation nodes can be imported, they cannot be assigned to this document type, because DocumentType nodes are readonly. All properties of the original notation are imported along with it (publicId and systemId); the deep parameter has no effect because Notation nodes cannot have children.

ProcessingInstruction

The processing instruction is imported along with its target and data properties; the deep parameter has no effect because ProcessingInstruction nodes cannot have children.

Return value

The new node in this document

Compatibility

Internet Explorer doesn't implement this method (it returns undefined).

In all supported browsers, event-handling attributes on imported elements are not active, and will need to be re-assigned.

Opera imports CDATASection nodes as Text nodes (ie. the node in this document has the nodeName #text and the nodeType 3).

Firefox 1.5 and 2 allow the import of Document and DocumentType nodes, an operation that should throw a DOMException (code 9: NOT_SUPPORTED_ERR code 9).

Safari won't import Attr or DocumentFragment nodes — it throws a DOMException as though the operation were not allowed (code 9: NOT_SUPPORTED_ERR code 9).

Additionally, Safari 3 in HTML mode¹ won't import Element nodes from XML that isn't XHTML if the deep argument is true, with the same exception. It does work for XHTML. It also works for other XML if importNode is called on the document you're importing from, however ...