Change cloneNode references to importNode

[frehner]

Description

Updated examples to use document.importNode() exclusively, and references to refer to both importNode and Node.cloneNode.

Motivation

document.importNode and Node.cloneNode are largely similar, but have one important difference; the timing of when the node is adopted. When using Node.cloneNode(), the content isn't adopted until it's either explicitly adopted or when it's appended to the document, so at a later point after calling cloneNode(). This falls into an edge-case annoyance where calling upgrade on nodes that aren't yet adopted causes them to not actually get upgraded. This real example from the Web Components discord demonstrates the edge-case:

class MyEl extends HTMLElement {
  constructor() {super(); console.log('MyEl constructor')}
}
customElements.define('my-el', MyEl)

const template = document.createElement('template')
template.innerHTML = '<my-el></my-el>'

const frag = template.content.cloneNode(true)

console.log(customElements.get('my-el')) // MyEl

customElements.upgrade(frag) // crickets
console.log('My el constructor should have ran already')

document.body.append(frag) // logs "MyEl constructor"

If you change from content.cloneNode() to document.importNode() then the constructor will run and the content is upgraded correctly.

So we would like to update the examples to show document.importNode() being used by default, and also update references/links to show it as an option next to cloneNode.

Additional details

Web components discord discussion https://discord.com/channels/767813449048260658/767813449048260661/1421037073829199994

Related issues and pull requests

[github-actions]

Preview URLs (13 pages)

• /en-US/docs/Web/API/CustomElementRegistry/getName
• /en-US/docs/Web/API/CustomElementRegistry/get
• /en-US/docs/Web/API/Document/importNode
• /en-US/docs/Web/API/DocumentFragment/getElementById
• /en-US/docs/Web/API/HTMLTemplateElement/content
• /en-US/docs/Web/API/Intersection_Observer_API
• /en-US/docs/Web/API/Node/cloneNode
• /en-US/docs/Web/API/ShadowRoot/elementFromPoint
• /en-US/docs/Web/API/Web_components/Using_templates_and_slots
• /en-US/docs/Web/API/Window/customElements
• /en-US/docs/Web/CSS/Reference/Selectors/::slotted
• /en-US/docs/Web/HTML/Reference/Elements/template
• /en-US/docs/Web/HTML/Reference/Global_attributes/exportparts

Flaws (3)

Note! 12 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Web/API/Web_components/Using_templates_and_slots
Title: Using templates and slots
Flaw count: 3

• macros:
  • Macro produces link /en-US/docs/Web/Web_Components/Using_custom_elements which is a redirect
  • Macro produces link /en-US/docs/Web/Web_Components/Using_shadow_DOM which is a redirect
  • Macro produces link /en-US/docs/Web/Web_Components/Using_templates_and_slots which is a redirect

(comment last updated: 2025-11-25 05:08:09)

[Josh-Cena]

If this is important, could you add a sentence to cloneNode (and importNode)?

[frehner]

If this is important, could you add a sentence to cloneNode (and importNode)?

How does that look?

[Josh-Cena]

If your argument for using importNode is for upgrade, why not point that out directly? There are significant use cases of <template> that aren't related to custom elements at all, and even some that do, do not suffer from this issue if the <template> is just used within the custom element constructor to populate the content—as the majority of our examples do. So it's not totally clear to me how big the impact is. I searched for .cloneNode(true) and we have a lot more usages with template.content; should all of them be replaced as well?

[frehner]

If your argument for using importNode is for upgrade, why not point that out directly? There are significant use cases of <template> that aren't related to custom elements at all, and even some that do, do not suffer from this issue if the <template> is just used within the custom element constructor to populate the content—as the majority of our examples do. So it's not totally clear to me how big the impact is. I searched for .cloneNode(true) and we have a lot more usages with template.content; should all of them be replaced as well?

I’m under the impression from the community that yes, we would like all these updated and that importNode should be the default.

I’ll see if I can get some people to chime in here.

[Josh-Cena]

Hi @frehner, any updates? Do you want to propose an updated version first so we can get other people to look at it? Perhaps someone from WHATWG?

[justinfagnani]

I think this is an important change to make.

If you don't know exactly what's in your template (like many libraries that accept or produce user-defined templates), then importNode() is nearly always the better API to use since custom elements will be upgraded.

[sorvell]

I would also suggest clearly explaining that the nodes in content, the template document fragment, exist in a separate document, not the main document. This helps explain why it's typically desirable to copy them with importNode rather than cloneNode.

Otherwise you get fairly unintuitive behavior that could manifest in odd ways. This could also be addressed in the pitfalls section.

const clone = template.content.cloneNode(true);
console.assert(clone.firstElementChild.ownerDocument === document) // fails.
const imported = document.importNode(template.content, true);
console.assert(imported.firstElementChild.ownerDocument === document) // works.

[Josh-Cena]

Thanks, both. Would you agree to globally replace cloneNode with importNode? Do you have specific wording suggestions for the warning?

[Josh-Cena]

Waiting until the note gets rewritten

[Josh-Cena]

Hi @frehner @justinfagnani @sorvell I've committed an updated version of the note:

The {{domxref("Node.cloneNode()")}} and {{domxref("Document.importNode()")}} methods both create a copy of a node. The difference is that importNode() clones the node in the context of the calling document, whereas cloneNode() uses the document of the node being cloned. The document context determines the {{domxref("CustomElementRegistry")}} for constructing any custom elements. For this reason, use document.importNode() to clone the content fragment so that custom element descendants are constructed using the definitions in the current document, rather than the separate document that owns the template content. See the {{domxref("Node.cloneNode()")}} page's examples for more details.

WDYT?

[Josh-Cena]

For cases like this, I think it's actually fine to use cloneNode because it's immediately appended, no?

[justinfagnani]

It may be fine, but IMO it's a lot easier to be consistent and use importNode everywhere.

[Josh-Cena]

I've done a global replacement for all cloneNode(true) calls on template.content.