👾 Omdomdom

Create, render, and patch virtual nodes

Omdomdom is intentionally very minimal. Its primary function is to produce HTML nodes from strings. Pull requests and issues welcome! ## Install **NPM** ```sh $ npm i omdomdom ``` Then import: ```js import { render, patch, create } from "omdomdom" create(...) render(...) patch(...) ``` **CDN** ```html ``` The CDN will set `window.Omdomdom` on your page. ## Virtual Node Structure If you're familiar with other virtual DOM implementations, then this will look familiar. :) ```js VirtualNode { // One of three value types are used: // - The tag name of the element // - "text" if text node // - "comment" if comment node type: String, // An object whose key/value pairs are the attribute // name and value, respectively attributes: Object., // Is set to `true` if a node is an `svg`, which tells // Omdomdom to treat it, and its children, as such isSVGContext: Boolean, // The content of a "text" or "comment" node content: String, // An array of virtual node children children: Array, // The real DOM node node: Node } ``` ## API ### `create(string|node)` The function takes one argument: an html string or a real DOM node. Either way, it will be converted into a virtual node. #### Option 1: HTML String ```js const html = "

I'm pink!

" const vNode = create(html) ``` If the value is indeed a string, then it will be passed to [`DOMParser`](https://developer.mozilla.org/en-US/docs/Web/API/DOMParser). #### Option 2: Node This is a more performant option if you have high confidence in the structure of your HTML string. ```js const html = "

I'm pink!

" const wrapper = document.createElement("div") wrapper.innerHTML = html const vNode = create(wrapper) ``` The main downside to this option is you lose the helpful error messaging DOMParser provides from option 1. This is usually best for simpler nodes. ### `render(vNode, targetNode)` Inserts your node somewhere on the page. ```js render(vNode, document.getElementById("root")) ``` Under the hood, all `render` does is use `targetNode.appendChild(vNode.node)`. ### `patch(nextVNode, oldVnode)` Updates your original (old) virtual node with changes from the next one. ```js const nextHtml = "

I'm new and fresh.

" patch(create(nextHtml), vNode) ``` Do note that any virtual nodes created as the first argument to `patch` are discarded. Again, the only virtual node tree you need to care about is the old one. ## Reconciliation Reconciliation works similar to React and others, by comparing an older (live) virtual DOM tree to a new (template) one. The live tree is then patched with changes from the template. ### Keys If you have elements in dynamically generated lists or where there's many siblings, use the `data-key` attribute to memoize the node between patches. ```html ``` The value for the attribute only needs to be unique among its sibling nodes. ### Performance If you think it can be improved, please contribute. :) ## Support Omdomdom works in all modern browsers and IE11. It requires no polyfills/dependencies.