yippee.fun
Precise DOM morphing
morphing
typescript
dom
joel.drapper.me
1<p align="center">
2 <img src="https://github.com/phlex-ruby/morphlex/assets/246692/128ebe6a-bdf3-4b88-8a40-f29df64b3ac8" alt="Morphlex" width="481">
3</p>
4
5Morphlex is a ~2.4KB (gzipped) DOM morphing library that transforms one DOM tree to match another while preserving element state and making minimal changes.
6
7## What makes Morphlex different?
8
91. No cascading mutations from inserts. Simple inserts should be one DOM operation.
102. No cascading mutations from removes. Simple removes should be one DOM operation.
113. No cascading mutations from partial sorts. Morphlex finds the longest increasing subsequence for near optimal partial sorts.
124. It uses `moveBefore` when available, preserving state.
135. It uses `isEqualNode`, but in a way that is sensitive to the value of form inputs.
146. It uses id sets inspired by Idiomorph.
15
16## Installation
17
18<kbd>npm install morphlex</kbd>
19
20Or use it directly from a CDN:
21
22```html
23<script type="module">
24 import { morph } from "https://www.unpkg.com/morphlex@latest/dist/morphlex.min.js"
25</script>
26```
27
28## Usage
29
30```javascript
31import { morph, morphInner } from "morphlex"
32
33// Morph the entire element
34morph(currentNode, newNode)
35
36// Morph only the children of the current node
37morphInner(currentNode, newNode)
38
39// Morph the entire document
40morphDocument(document, newDocument)
41```
42
43## Options
44
45Both `morph` and `morphInner` accept an optional third parameter for configuration:
46
47```javascript
48morph(currentNode, newNode, {
49 preserveChanges: true,
50 beforeNodeAdded: (parent, node, insertionPoint) => {
51 console.log("Adding node:", node)
52 return true // return false to prevent addition
53 },
54})
55```
56
57### Available Options
58
59- **`preserveChanges`**: When `true`, preserves modified form inputs during morphing. This prevents user-entered data from being overwritten. Default: `false`
60
61- **`beforeNodeVisited`**: Called before a node is visited during morphing. Return `false` to skip morphing this node.
62
63- **`afterNodeVisited`**: Called after a node has been visited and morphed.
64
65- **`beforeNodeAdded`**: Called before a new node is added to the DOM. Return `false` to prevent adding the node.
66
67- **`afterNodeAdded`**: Called after a node has been added to the DOM.
68
69- **`beforeNodeRemoved`**: Called before a node is removed from the DOM. Return `false` to prevent removal.
70
71- **`afterNodeRemoved`**: Called after a node has been removed from the DOM.
72
73- **`beforeAttributeUpdated`**: Called before an attribute is updated on an element. Return `false` to prevent the update.
74
75- **`afterAttributeUpdated`**: Called after an attribute has been updated on an element.
76
77- **`beforeChildrenVisited`**: Called before an element's children are visited during morphing. Return `false` to skip visiting children.
78
79- **`afterChildrenVisited`**: Called after an element's children have been visited and morphed.