Precise DOM morphing
morphing
typescript
dom
Update the README
+45
-24
+45
-24
README.md
+45
-24
README.md
···
2
2
<img src="https://github.com/phlex-ruby/morphlex/assets/246692/128ebe6a-bdf3-4b88-8a40-f29df64b3ac8" alt="Morphlex" width="481">
3
3
</p>
4
4
5
-
Morphlex is a tiny, optimal DOM morphing library written in TypeScript. DOM morphing is the process of transforming one DOM tree to reflect another, while preserving the state of the original tree and making as few changes as possible.
5
+
Morphlex is a 2KB DOM morphing library that transforms one DOM tree to match another while preserving element state and making minimal changes.
6
6
7
-
Morphlex uses ID Sets — a concept pioneered by [Idiomorph](https://github.com/bigskysoftware/idiomorph) — to match nodes with deeply nested identified elements.
8
-
9
-
## ID Sets
10
-
11
-
Each element is tagged with the set of IDs it contains, allowing for more optimal matching.
12
-
13
-
Failing an ID Set match, Morphlex will search for the next best match by tag name. If no element can be found, the reference element will be deeply cloned instead.
7
+
## Installation
14
8
15
-
## Try it out
9
+
```bash
10
+
npm install morphlex
11
+
```
16
12
17
-
The easiest way to try out Morphlex is to import it directly from UNPKG.
13
+
Or use it directly from a CDN:
18
14
19
15
```html
20
16
<script type="module">
21
17
import { morph } from "https://www.unpkg.com/morphlex@0.0.16/dist/morphlex.min.js"
22
-
23
-
morph(currentNode, referenceNode)
24
-
morphInner(currentNode, referenceNode)
25
18
</script>
26
19
```
27
20
28
-
Alternatively, you can install it via npm and import it into your project.
29
-
30
-
```bash
31
-
npm install morphlex --save
32
-
```
21
+
## Usage
33
22
34
23
```javascript
35
-
import { morph } from "morphlex"
24
+
import { morph, morphInner } from "morphlex"
36
25
26
+
// Morph the entire element
37
27
morph(currentNode, referenceNode)
28
+
29
+
// Morph only the inner content
30
+
morphInner(currentNode, referenceNode)
38
31
```
39
32
40
-
The `currentNode` will be morphed into the state of the `referenceNode`. The `referenceNode` will not be mutated in this process.
33
+
The `currentNode` is transformed to match the `referenceNode`. The `referenceNode` remains unchanged.
34
+
35
+
## How it works
36
+
37
+
Morphlex uses a smart matching algorithm that produces minimal DOM operations for common patterns like inserts, deletes, and reordering.
38
+
39
+
### Matching strategy
40
+
41
+
When morphing child nodes, Morphlex tries multiple matching strategies in order of specificity:
42
+
43
+
1. **Exact match** — Nodes that are completely identical (`isEqualNode`)
44
+
2. **ID match** — Elements with the same `id` attribute
45
+
3. **ID set match** — Elements containing the same nested IDs (see below)
46
+
4. **Tag match** — Elements with the same tag name, or nodes with the same type
41
47
42
-
## Contributing
48
+
This cascading approach means most updates find optimal matches quickly, while still handling edge cases gracefully.
43
49
44
-
If you find a bug or have a feature request, please open an issue. If you want to contribute, please open a pull request.
50
+
### ID sets
45
51
46
-
> [!TIP]
47
-
> Morphlex is written in **[TypeScript](https://www.typescriptlang.org)** because it helps us avoid a whole category of potential bugs. If you’re more comfortable writing JavaScript, you’re very welcome to open a Pull Request modifying the `dist/morphlex.js` file. I’m happy to take care of the TypeScript conversion myself. — Joel
52
+
ID sets are inspired by [Idiomorph](https://github.com/bigskysoftware/idiomorph). Each element is tagged with the set of IDs it contains, including deeply nested ones. This helps match elements even when they've moved or been restructured.
53
+
54
+
For example, if you have a card with `id="card-123"` nested inside a container, the container's ID set includes `"card-123"`. When morphing, Morphlex can match the container based on that nested ID, even if the container itself has no ID.
55
+
56
+
### Minimal operations
57
+
58
+
After matching, Morphlex processes nodes in order and makes the minimum number of DOM operations:
59
+
60
+
- Matched elements are moved into position (if needed) and recursively morphed
61
+
- New nodes are inserted at the correct position
62
+
- Unmatched nodes are removed
63
+
64
+
This means operations like sorting a list or inserting items in the middle produce exactly the moves you'd expect, with no unnecessary removals or recreations.
65
+
66
+
## Contributing
67
+
68
+
Found a bug or have a feature request? Open an issue. Want to contribute? Open a pull request.