bigskysoftware
Explain Settling Process Before Introducing Settle Options in Docs
Today, I began reading the HTMX docs to start getting acquainted with the core concepts. While reading the "Swap Options" section, I noticed that several of the options described behavior around content "settling" after insert, a concept with which I wasn't familiar.
Further reading revealed that settling is explained under the "CSS Transitions - Details" section, but this comes after the introduction of the swap options. Is there a way the explanation of settling be pulled up before the swap options, so that the reader already knows what's being referenced?
Would also love more detailed docs on the HTMX request/swap/settle cycle. After reading the docs and playing around with code, I'm still confused.
From the docs, I thought there would be distinct "swap" and then "settling" phases. But if I add "settle:1s", I see that htmx-swapping, htmx-added and htmx-settling are all applied for the full duration.
~~I also noticed that, during settling, new content is shown on the page, but new classes that I've applied to elements server-side don't get applied until the settling is over.~~ (Updated below. This is documented.)
I'm not sure whether these behaviors are as expected, or a bug.
Oh, I did find some useful info here: in the details for CSS Transitions:
To understand how CSS transitions actually work in htmx, you must understand the underlying swap & settle model that htmx uses.
When new content is received from a server, before the content is swapped in, the existing content of the page is examined for elements that match by the id attribute. If a match is found for an element in the new content, the attributes of the old content are copied onto the new element before the swap occurs. The new content is then swapped in, but with the old attribute values. Finally, the new attribute values are swapped in, after a “settle” delay (20ms by default). A little crazy, but this is what allows CSS transitions to work without any javascript by the developer.
Aha. I'd been thinking it was doing DOM updates to keep the same DOM Node on the page. This does explain why animations don't fire until after the settle period. So I guess that's expected behavior. (But it seems to mean that you can't do https://htmx.org/examples/animations/#fade-in-on-addition and https://htmx.org/docs/#css_transitions at the same time. 😞)