``` Snabbdom allows swapping event handlers between renders. This happens without actually touching the event handlers attached to the DOM. Note, however, that **you should be careful when sharing event handlers between vnodes**, because of the technique this module uses to avoid re-binding event handlers to the DOM. (And in general, sharing data between vnodes is not guaranteed to work, because modules are allowed to mutate the given data). In particular, you should **not** do something like this: ```mjs // Does not work const sharedHandler = { change: function (e) { console.log("you chose: " + e.target.value); }, }; h("div", [ h("input", { props: { type: "radio", name: "test", value: "0" }, on: sharedHandler, }), h("input", { props: { type: "radio", name: "test", value: "1" }, on: sharedHandler, }), h("input", { props: { type: "radio", name: "test", value: "2" }, on: sharedHandler, }), ]); ``` For many such cases, you can use array-based handlers instead (described above). Alternatively, simply make sure each node is passed unique `on` values: ```mjs // Works const sharedHandler = function (e) { console.log("you chose: " + e.target.value); }; h("div", [ h("input", { props: { type: "radio", name: "test", value: "0" }, on: { change: sharedHandler }, }), h("input", { props: { type: "radio", name: "test", value: "1" }, on: { change: sharedHandler }, }), h("input", { props: { type: "radio", name: "test", value: "2" }, on: { change: sharedHandler }, }), ]); ``` ## SVG SVG just works when using the `h` function for creating virtual nodes. SVG elements are automatically created with the appropriate namespaces. ```mjs const vnode = h("div", [ h("svg", { attrs: { width: 100, height: 100 } }, [ h("circle", { attrs: { cx: 50, cy: 50, r: 40, stroke: "green", "stroke-width": 4, fill: "yellow", }, }), ]), ]); ``` See also the [SVG example](./examples/svg) and the [SVG Carousel example](./examples/carousel-svg/). ### Classes in SVG Elements Certain browsers (like IE <=11) [do not support `classList` property in SVG elements](http://caniuse.com/#feat=classlist). Because the _class_ module internally uses `classList`, it will not work in this case unless you use a [classList polyfill](https://www.npmjs.com/package/classlist-polyfill). (If you don't want to use a polyfill, you can use the `class` attribute with the _attributes_ module). ## Thunks The `thunk` function takes a selector, a key for identifying a thunk, a function that returns a vnode and a variable amount of state parameters. If invoked, the render function will receive the state arguments. `thunk(selector, key, renderFn, [stateArguments])` The `renderFn` is invoked only if the `renderFn` is changed or `[stateArguments]` array length or it's elements are changed. The `key` is optional. It should be supplied when the `selector` is not unique among the thunks siblings. This ensures that the thunk is always matched correctly when diffing. Thunks are an optimization strategy that can be used when one is dealing with immutable data. Consider a simple function for creating a virtual node based on a number. ```mjs function numberView(n) { return h("div", "Number is: " + n); } ``` The view depends only on `n`. This means that if `n` is unchanged, then creating the virtual DOM node and patching it against the old vnode is wasteful. To avoid the overhead we can use the `thunk` helper function. ```mjs function render(state) { return thunk("num", numberView, [state.number]); } ``` Instead of actually invoking the `numberView` function this will only place a dummy vnode in the virtual tree. When Snabbdom patches this dummy vnode against a previous vnode, it will compare the value of `n`. If `n` is unchanged it will simply reuse the old vnode. This avoids recreating the number view and the diff process altogether. The view function here is only an example. In practice thunks are only relevant if you are rendering a complicated view that takes significant computational time to generate. ## JSX ### TypeScript Add the following options to your `tsconfig.json`: ```json { "compilerOptions": { "jsx": "react", "jsxFactory": "jsx" } } ``` Then make sure that you use the `.tsx` file extension and import the `jsx` function at the top of the file: ```tsx import { jsx, VNode } from "snabbdom"; const node: VNode = ( ); ``` ### Babel Add the following options to your babel configuration: ```json { "plugins": [ [ "@babel/plugin-transform-react-jsx", { "pragma": "jsx" } ] ] } ``` Then import the `jsx` function at the top of the file: ```jsx import { jsx } from "snabbdom"; const node = ( ); ``` ## Virtual Node **Properties** - [sel](#sel--string) - [data](#data--object) - [children](#children--array) - [text](#text--string) - [elm](#elm--element) - [key](#key--string--number) ### sel : String The `.sel` property of a virtual node is the CSS selector passed to [`h()`](#snabbdomh) during creation. For example: `h('div#container', {}, [...])` will create a a virtual node which has `div#container` as its `.sel` property. ### data : Object The `.data` property of a virtual node is the place to add information for [modules](#modules-documentation) to access and manipulate the real DOM element when it is created; Add styles, CSS classes, attributes, etc. The data object is the (optional) second parameter to [`h()`](#snabbdomh) For example `h('div', {props: {className: 'container'}}, [...])` will produce a virtual node with ```mjs ({ props: { className: "container", }, }); ``` as its `.data` object. ### children : Array The `.children` property of a virtual node is the third (optional) parameter to [`h()`](#snabbdomh) during creation. `.children` is simply an Array of virtual nodes that should be added as children of the parent DOM node upon creation. For example `h('div', {}, [ h('h1', {}, 'Hello, World') ])` will create a virtual node with ```mjs [ { sel: "h1", data: {}, children: undefined, text: "Hello, World", elm: Element, key: undefined, }, ]; ``` as its `.children` property. ### text : string The `.text` property is created when a virtual node is created with only a single child that possesses text and only requires `document.createTextNode()` to be used. For example: `h('h1', {}, 'Hello')` will create a virtual node with `Hello` as its `.text` property. ### elm : Element The `.elm` property of a virtual node is a pointer to the real DOM node created by snabbdom. This property is very useful to do calculations in [hooks](#hooks) as well as [modules](#modules-documentation). ### key : string | number The `.key` property is created when a key is provided inside of your [`.data`](#data--object) object. The `.key` property is used to keep pointers to DOM nodes that existed previously to avoid recreating them if it is unnecessary. This is very useful for things like list reordering. A key must be either a string or a number to allow for proper lookup as it is stored internally as a key/value pair inside of an object, where `.key` is the key and the value is the [`.elm`](#elm--element) property created. If provided, the `.key` property must be unique among sibling elements. For example: `h('div', {key: 1}, [])` will create a virtual node object with a `.key` property with the value of `1`. ## Structuring applications Snabbdom is a low-level virtual DOM library. It is unopinionated with regards to how you should structure your application. Here are some approaches to building applications with Snabbdom. - [functional-frontend-architecture](https://github.com/paldepind/functional-frontend-architecture) – a repository containing several example applications that demonstrates an architecture that uses Snabbdom. - [Cycle.js](https://cycle.js.org/) – "A functional and reactive JavaScript framework for cleaner code" uses Snabbdom - [Vue.js](http://vuejs.org/) use a fork of snabbdom. - [scheme-todomvc](https://github.com/amirouche/scheme-todomvc/) build redux-like architecture on top of snabbdom bindings. - [kaiju](https://github.com/AlexGalays/kaiju) - Stateful components and observables on top of snabbdom - [Tweed](https://tweedjs.github.io) – An Object Oriented approach to reactive interfaces. - [Cyclow](http://cyclow.js.org) - "A reactive frontend framework for JavaScript" uses Snabbdom - [Tung](https://github.com/Reon90/tung) – A JavaScript library for rendering html. Tung helps to divide html and JavaScript development. - [sprotty](https://github.com/theia-ide/sprotty) - "A web-based diagramming framework" uses Snabbdom. - [Mark Text](https://github.com/marktext/marktext) - "Realtime preview Markdown Editor" build on Snabbdom. - [puddles](https://github.com/flintinatux/puddles) - "Tiny vdom app framework. Pure Redux. No boilerplate." - Built with :heart: on Snabbdom. - [Backbone.VDOMView](https://github.com/jcbrand/backbone.vdomview) - A [Backbone](http://backbonejs.org/) View with VirtualDOM capability via Snabbdom. - [Rosmaro Snabbdom starter](https://github.com/lukaszmakuch/rosmaro-snabbdom-starter) - Building user interfaces with state machines and Snabbdom. - [Pureact](https://github.com/irony/pureact) - "65 lines implementation of React incl Redux and hooks with only one dependency - Snabbdom" - [Snabberb](https://github.com/tobymao/snabberb) - A minimalistic Ruby framework using [Opal](https://github.com/opal/opal) and Snabbdom for building reactive views. - [WebCell](https://github.com/EasyWebApp/WebCell) - Web Components engine based on JSX & TypeScript Be sure to share it if you're building an application in another way using Snabbdom. ## Common errors ```text Uncaught NotFoundError: Failed to execute 'insertBefore' on 'Node': The node before which the new node is to be inserted is not a child of this node. ``` The reason for this error is reusing of vnodes between patches (see code example), snabbdom stores actual dom nodes inside the virtual dom nodes passed to it as performance improvement, so reusing nodes between patches is not supported. ```mjs const sharedNode = h("div", {}, "Selected"); const vnode1 = h("div", [ h("div", {}, ["One"]), h("div", {}, ["Two"]), h("div", {}, [sharedNode]), ]); const vnode2 = h("div", [ h("div", {}, ["One"]), h("div", {}, [sharedNode]), h("div", {}, ["Three"]), ]); patch(container, vnode1); patch(vnode1, vnode2); ``` You can fix this issue by creating a shallow copy of the object (here with object spread syntax): ```mjs const vnode2 = h("div", [ h("div", {}, ["One"]), h("div", {}, [{ ...sharedNode }]), h("div", {}, ["Three"]), ]); ``` Another solution would be to wrap shared vnodes in a factory function: ```mjs const sharedNode = () => h("div", {}, "Selected"); const vnode1 = h("div", [ h("div", {}, ["One"]), h("div", {}, ["Two"]), h("div", {}, [sharedNode()]), ]); ``` ## Opportunity for community feedback Pull requests that the community may care to provide feedback on should be merged after such opportunity of a few days was provided.