Morphing One DOM Tree To Another – idiomorph

Preview:

Description:

Yet another DOM merging library that allows you to morph one DOM tree to another.

Inspired by the morphdom library, which is a lightweight module for morphing an existing DOM node tree to match a target DOM node tree.

Inspiration:

Both morphdom and nanomorph use the id property of a node to match up elements within a given set of sibling nodes. When an id match is found, the existing element is often not removed from the DOM, but is morphed in place to the new content. This preserves the node in the DOM and allows state (such as focus) to be retained. However, in both these algorithms, the structure of the children of sibling nodes is not considered when morphing two nodes: only the ids of the nodes are considered. This is due to performance considerations: it is not feasible to recurse through all the children of siblings when matching things up.

idiomorph takes a slightly different approach: before node-matching occurs, both the new content and the old content are processed to create id sets, a mapping of elements to a set of all ids found within that element. That is, the set of all ids in all children of the element, plus the elements’ id, if any.

id sets can be computed relatively efficiently via a query selector + a bottom up algorithm.

Given an id set, you can now adopt a broader sense of “matching” than simply using id matching: if the intersection between the id sets of element 1 and element 2 is non-empty, they match. This allows idiomorph to relatively quickly match elements based on structural information from children, who contribute to a parents id set, which allows for better overall matching when compared with id-based matching.

How to use it:

1. Download and load the idiomorph.js in the document.

<script src="/path/to/src/idiomorph.js"></script>

2. Morph the existing node to another.

Idiomorph.morph(existingNode, newNode);
// OR
Idiomorph.morph(existingNode, 'Any HTML Content Here');

3. Available options.

Idiomorph.morph(existingNode, newNode,{
  morphStyle: "outerHTML", // innerHTML or outerHTML
  ignoreActive: false,
  ignoreActiveValue: false,
  restoreFocus: true,
  callbacks: {
    beforeNodeAdded: noOp,
    afterNodeAdded: noOp,
    beforeNodeMorphed: noOp,
    afterNodeMorphed: noOp,
    beforeNodeRemoved: noOp,
    afterNodeRemoved: noOp,
    beforeAttributeUpdated: noOp,
  },
  head: {
    style: "merge",
    shouldPreserve: function (elt) {
      return elt.getAttribute("im-preserve") === "true";
    },
    shouldReAppend: function (elt) {
      return elt.getAttribute("im-re-append") === "true";
    },
    shouldRemove: noOp,
    afterHeadMorphed: noOp,
  },
});

Changelog:

v0.7.3 (03/06/2025)

• Remove twoPass option.
• Remove beforeNodePantried callback option.
• New on-by-default restoreFocus option.
• Bugfixes

v0.4.0 (12/23/2024)

• Exclude document.body when morphing with ignoreActiveValue: true
• Improve morph support for <template> elements
• Fix type errors
• bugfix: fix htmx integration when innerHTML swap strategy is used
• Fix early return
• Add –fail-only option to fail the test suite in CI when an it.only is left in
• Iterating over the NamedNodeMap returned by Element.prototype.attributes is unsafe and vulnerable to race conditions
• Fix persistent ids being softMatched when they shouldn’t
• improve softMatch to not retain state on morph if oldNode has id
• Add twoPass option for additional state retention
• Add prettier to normalize code style

v0.3.0 (12/17/2024)

• get something working with testing experimental moveBefore.

v0.1.0 (12/14/2023)

• bugfixes

v0.0.7 (09/13/2022)

• clean up findSoftMatch()