htmx 2.0.0 breaks <template> elements inside Web Components

[luontola]

When a htmx response contains <template> elements inside a Web Component element, htmx 1.9.12 adds them to the DOM, but htmx 2.0.0 removes them. This breaks web components which use that method to receive data from the server.

Example app

1. Save this file as server.py

from flask import Flask

app = Flask(__name__)


@app.route("/")
def home():
    # Works with https://unpkg.com/[email protected]/dist/htmx.min.js
    # Doesn't work with https://unpkg.com/[email protected]/dist/htmx.min.js
    return """
<script src="https://unpkg.com/[email protected]/dist/htmx.min.js"></script>
<script type="module">
class HelloWorldElement extends HTMLElement {
  constructor() {
    super();
  }

  connectedCallback() {
    const template = this.querySelector("template");
    console.log("template:", template, template?.content.textContent)
  }
}
customElements.define('hello-world', HelloWorldElement);
</script>

<div hx-get="/lazy" hx-swap="outerHTML" hx-target="this" hx-trigger="load">
</div>

</div>
"""


@app.route("/lazy")
def lazy():
    return """
<hello-world>
<template>Lazy loaded content</template>
</hello-world>
"""

2. Run the app with the commands:

pip install Flask
flask --app server.py --debug run

3. Open the app at http://127.0.0.1:5000/

4. Open the JavaScript console and see what is printed there on page load

Expected result

• The code prints template: <template>​…​</template>​ Lazy loaded content
• This is what happens on htmx 1.9.12

Actual result

• The code prints template: null undefined
• This is what happens on htmx 2.0.0

[kubeden]

Hey, after some investigation, I found out the following function added to 2.0.0 which does not exist in 1.9.12:

      // oob swaps
      findAndSwapOobElements(fragment, settleInfo)
      forEach(findAll(fragment, 'template'), /** @param {HTMLTemplateElement} template */function(template) {
        findAndSwapOobElements(template.content, settleInfo)
        if (template.content.childElementCount === 0) {
        // Avoid polluting the DOM with empty templates that were only used to encapsulate oob swap
          template.remove()
        }
      })

You can see here that there is a comment "// Avoid polluting the DOM with empty templates that were only used to encapsulate oob swap"

Now, I tested your code and upon encapsulating the "Lazy loaded content" inside a <p> tag, it is being correctly returned.

I am assuming the <template> is considered empty if there is no tag inside.

A fix to this might be to instead of having a plaintext in your <template/>, to instead have text inside a tag (p h2 etc.)

Plaintext inside the template:

P tag inside the template:

Otherwise the function might need to be deleted or change this line:

if (template.content.childElementCount === 0) {

To (or similar)... not sure about this, though. Someone from the core team should jump into the discussion.

if (template.content && template.content.textContent && template.content.textContent.trim().length > 0) {

[luontola]

Does htmx create some of its own templates and use them for oob swap? It seems dangerous to find and remove arbitrary template elements, instead of just those that htmx has created for a specific purpose. Maybe the oob swap templates could be tagged with a custom class or attribute for identification, and only delete those?

[kubeden]

Continuing the discussion with more investigation

The following function seems to be taking care of OOB elements:

findAndSwapOobElements(fragment, settleInfo)

function findAndSwapOobElements(fragment, settleInfo) {
    forEach(findAll(fragment, '[hx-swap-oob], [data-hx-swap-oob]'), function(oobElement) {
      if (htmx.config.allowNestedOobSwaps || oobElement.parentElement === null) {
        const oobValue = getAttributeValue(oobElement, 'hx-swap-oob')
        if (oobValue != null) {
          oobSwap(oobValue, oobElement, settleInfo)
        }
      } else {
        oobElement.removeAttribute('hx-swap-oob')
        oobElement.removeAttribute('data-hx-swap-oob')
      }
    })
  }

Now back to oob swaps again:

      // oob swaps
      findAndSwapOobElements(fragment, settleInfo)
      forEach(findAll(fragment, 'template'), /** @param {HTMLTemplateElement} template */function(template) {
        findAndSwapOobElements(template.content, settleInfo)
        if (template.content.childElementCount === 0) {
        // Avoid polluting the DOM with empty templates that were only used to encapsulate oob swap
          template.remove()
        }
      })

We are looping through each occurance of the fragment 'template' from the response of the findAll function (see htmx official doc) so it seems htmx is indeed looping through all elements of some type:

Maybe if the findAndSwapOobElements() is assigned to a variable to introduce a second check (if HTMX modified the template) before removing the OOB template, that would help?

forEach(findAll(fragment, 'template'), /** @param {HTMLTemplateElement} template */function(template) {
    let wasModified = findAndSwapOobElements(template.content, settleInfo)
    if (wasModified && template.content.childNodes.length === 0) {
      // Only remove if HTMX modified it and it's completely empty
      template.remove()
    }
  })

But then... I think this is starting a different discussion that maybe needs a new issue opened.

So it seems we are back to the initial workaround or "fix":

🚧 Workaround: don't leave plaintext inside <template>
✅ Fix: check if there is at least one character before removing (not sure if that's a good practice... I need suggestions here); if someone approves this direction, I would be happy to open a pull request.

[kubeden]

Should I tag someone from the maintainers team? Or should I directly start PR to kickoff a discussion inside?

I'm new to this whole open source contributing thing. 🥲

[Telroshan]

Hello @kubeden, haven't had much time lately to investigate issues, a bugfix PR would be very welcome as per our contribution guidelines:

Correspondingly, it is fine to directly PR bugfixes for behavior that htmx already guarantees, but please check if there's an issue first, and if you're not sure whether this is a bug, make an issue where we can hash it out..

So if you feel like it, sure go for it!