morphdom

What is morphdom?

morphdom is a lightweight JavaScript library that efficiently morphs one DOM tree into another. It is useful for updating the DOM in a performant way, especially in scenarios where you need to apply changes to the DOM without reloading the entire page.

What are morphdom's main functionalities?

Basic DOM Morphing

This feature allows you to morph one DOM element into another. The `morphdom` function takes two arguments: the source element and the target HTML string or element. It efficiently updates the source element to match the target.

const morphdom = require('morphdom');
const fromNode = document.getElementById('from');
const toNode = document.getElementById('to');
morphdom(fromNode, toNode.innerHTML);

Preserve State

This feature allows you to preserve the state of certain elements during the morphing process. The `onBeforeElUpdated` callback can be used to prevent specific elements from being updated if they are already equal.

const morphdom = require('morphdom');
const fromNode = document.getElementById('from');
const toNode = document.getElementById('to');
morphdom(fromNode, toNode.innerHTML, {
  onBeforeElUpdated: function(fromEl, toEl) {
    if (fromEl.isEqualNode(toEl)) {
      return false;
    }
  }
});

Custom Element Handling

This feature allows you to handle custom logic for discarding elements. The `onBeforeNodeDiscarded` callback can be used to prevent certain elements from being removed from the DOM.

const morphdom = require('morphdom');
const fromNode = document.getElementById('from');
const toNode = document.getElementById('to');
morphdom(fromNode, toNode.innerHTML, {
  onBeforeNodeDiscarded: function(node) {
    if (node.classList && node.classList.contains('no-discard')) {
      return false;
    }
  }
});

Other packages similar to morphdom

snabbdom

Snabbdom is a virtual DOM library with a focus on simplicity, modularity, and performance. It allows you to create a virtual DOM tree and efficiently update the real DOM to match it. Compared to morphdom, Snabbdom provides a more comprehensive virtual DOM implementation and is often used in larger applications.

diffhtml

diffhtml is a library for diffing and patching the DOM. It provides a declarative way to update the DOM by comparing the current state with a new state and applying the minimal set of changes. diffhtml offers more features for complex DOM updates compared to morphdom.

domdiff

domdiff is a minimal library for diffing and patching the DOM. It focuses on providing a lightweight solution for updating the DOM with minimal overhead. While it is similar to morphdom in terms of functionality, domdiff is more lightweight and may be suitable for simpler use cases.

README

morphdom

NOTE: This module is experimental, but seems to work in the latest browsers. Use at own risk!

Simple module for morphing an existing DOM node tree to match a target DOM node tree. It's fast and works with the real DOM—no virtual DOM here!

The transformation is done in a single pass and is designed to minimize changes to the DOM while still ensuring that the morphed DOM exactly matches the target DOM. In addition, the algorithm used by this module will automatically match up elements that have corresponding IDs and that are found in both the original and target DOM tree.

NOTE: This module will modify both the original and target DOM node tree during the transformation. It is assumed that the target DOM node tree will be discarded after the original DOM node tree is morphed.

Usage

var morphdom = require('morphdom');

var el1 = document.createElement('div');
el1.className = 'foo';

var el2 = document.createElement('div');
el2.className = 'bar';

morphdom(el1, el2);

expect(el1.className).to.equal('bar');

API

morphdom(fromNode, toNode, options) : Node

The morphdom(fromNode, toNode, options) function supports the following arguments:

• fromNode (Node)- The node to morph
• toNode (Node) - The node that the fromNode should be morphed to
• options (Object) - See below for supported options

The returned value will typically be the fromNode. However, in situations where the fromNode is not compatible with the toNode (either different node type or different tag name) then a different DOM node will be returned.

Supported options (all optional):

• onNodeDiscarded (Function(node)) - A function that will called when a Node in the from tree has been discarded and will no longer exist in the final DOM tree.
• onBeforeMorphEl (Function(fromEl, toEl)) - A function that will called when a HTMLElement in the from tree is about to be morphed. If the listener function returns false then the element will be skipped.
• onBeforeMorphElChildren (Function(fromEl, toEl)) - A function that will called when the children of an HTMLElement in the from tree are about to be morphed. If the listener function returns false then the child nodes will be skipped.

var morphdom = require('morphdom');
var morphedNode = morphdom(fromNode, toNode, options);

Maintainers

• Patrick Steele-Idem (Twitter: @psteeleidem)

Contribute

Pull Requests welcome. Please submit Github issues for any feature enhancements, bugs or documentation problems.

License

ISC