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

• /en-US/docs/Web/API/Document/importNode
• /en-US/docs/Web/API/HTMLTemplateElement/content
• /en-US/docs/Web/API/Node/cloneNode
• /en-US/docs/Web/API/Web_components/Using_templates_and_slots
• /en-US/docs/Web/HTML/Reference/Elements/template

Flaws (3)

Note! 4 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-10-20 15:33:46)

[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.