snabbdom

A virtual DOM library with a focus on simplicity, modularity, powerful features
and performance.

---



Thanks to Browserstack for providing access to
their great cross-browser testing tools.

---

English | 简体中文 | Hindi

Introduction

Virtual DOM is awesome. It allows us to express our application's view
as a function of its state. But existing solutions were way too
bloated, too slow, lacked features, had an API biased towards OOP
, and/or lacked features I needed.

Snabbdom consists of an extremely simple, performant, and extensible
core that is only ≈ 200 SLOC. It offers a modular architecture with
rich functionality for extensions through custom modules. To keep the
core simple, all non-essential functionality is delegated to modules.

You can mold Snabbdom into whatever you desire! Pick, choose, and
customize the functionality you want. Alternatively you can just use
the default extensions and get a virtual DOM library with high
performance, small size, and all the features listed below.

Features

- Core features
- About 200 SLOC – you could easily read through the entire core and fully
understand how it works.
- Extendable through modules.
- A rich set of hooks available, both per vnode and globally for modules,
to hook into any part of the diff and patch process.
- Splendid performance. Snabbdom is among the fastest virtual DOM libraries.
- Patch function with a function signature equivalent to a reduce/scan
function. Allows for easier integration with a FRP library.
- Features in modules
- h function for easily creating virtual DOM nodes.
- SVG _just works_ with the h helper.
- Features for doing complex CSS animations.
- Powerful event listener functionality.
- Thunks to optimize the diff and patch process even further.
- JSX support, including TypeScript types
- Third party features
- Server-side HTML output provided by snabbdom-to-html.
- Compact virtual DOM creation with snabbdom-helpers.
- Template string support using snabby.
- Virtual DOM assertion with snabbdom-looks-like

Example

``mjs
import {
init,
classModule,
propsModule,
styleModule,
eventListenersModule,
h
} from "snabbdom";

const patch = init([
// Init patch function with chosen modules
classModule, // makes it easy to toggle classes
propsModule, // for setting properties on DOM elements
styleModule, // handles styling on elements with support for animations
eventListenersModule // attaches event listeners
]);

const container = document.getElementById("container");

const vnode = h(
"div#container.two.classes",
{ on: { click: () => console.log("div clicked") } },
[
h("span", { style: { fontWeight: "bold" } }, "This is bold"),
" and this is just normal text",
h("a", { props: { href: "/foo" } }, "I'll take you places!")
]
);
// Patch into empty DOM element – this modifies the DOM as a side effect
patch(container, vnode);

const newVnode = h(
"div#container.two.classes",
{ on: { click: () => console.log("updated div clicked") } },
[
h(
"span",
{ style: { fontWeight: "normal", fontStyle: "italic" } },
"This is now italic type"
),
" and this is still just normal text",
h("a", { props: { href: "/bar" } }, "I'll take you places!")
]
);
// Second patch invocation
patch(vnode, newVnode); // Snabbdom efficiently updates the old view to the new state
`

More examples

- Animated reordering of elements
- Hero transitions
- SVG Carousel

---

Table of contents

- Core documentation
- init
- patch
- Unmounting
- h
- fragment (experimental)
- toVNode
- Hooks
- Overview
- Usage
- The init hook
- The insert hook
- The remove hook
- The destroy hook
- Creating modules
- Modules documentation
- The class module
- The props module
- The attributes module
- The dataset module
- The style module
- Custom properties (CSS variables)
- Delayed properties
- Set properties on remove
- Set properties on destroy
- The eventlisteners module
- SVG
- Classes in SVG Elements
- Thunks
- JSX
- TypeScript
- Babel
- Virtual Node
- sel : String
- data : Object
- children : Array\
- text : string
- elm : Element
- key : string | number
- Structuring applications

* Related packages

- Common errors
- Opportunity for community feedback

Core documentation

The core of Snabbdom provides only the most essential functionality.
It is designed to be as simple as possible while still being fast and
extendable.

$3

The core exposes only one single function init. This init
takes a list of modules and returns a patch function that uses the
specified set of modules.

`mjs
import { classModule, styleModule } from "snabbdom";

const patch = init([classModule, styleModule]);
`

$3

The patch function returned by init takes two arguments. The first
is a DOM element or a vnode representing the current view. The second
is a vnode representing the new, updated view.

If a DOM element with a parent is passed, newVnode will be turned
into a DOM node, and the passed element will be replaced by the
created DOM node. If an old vnode is passed, Snabbdom will efficiently
modify it to match the description in the new vnode.

Any old vnode passed must be the resulting vnode from a previous call
to patch. This is necessary since Snabbdom stores information in the
vnode. This makes it possible to implement a simpler and more
performant architecture. This also avoids the creation of a new old
vnode tree.

`mjs
patch(oldVnode, newVnode);
`

#### Unmounting

While there is no API specifically for removing a VNode tree from its mount point element, one way of almost achieving this is providing a comment VNode as the second argument to patch, such as:

`mjs
patch(
oldVnode,
h("!", {
hooks: {
post: () => {
/ patch complete /
}
}
})
);
`

Of course, then there is still a single comment node at the mount point.

$3

It is recommended that you use h to create vnodes. It accepts a
tag/selector as a string, an optional data object, and an
optional string or an array of children.

`mjs
import { h } from "snabbdom";

const vnode = h("div#container", { style: { color: "#000" } }, [
h("h1.primary-title", "Headline"),
h("p", "A paragraph")
]);
`

$3

Caution: This feature is currently experimental and must be opted in.
Its API may be changed without a major version bump.

`mjs
const patch = init(modules, undefined, {
experimental: {
fragments: true
}
});
`

Creates a virtual node that will be converted to a document fragment containing the given children.

`mjs
import { fragment, h } from "snabbdom";

const vnode = fragment(["I am", h("span", [" a", " fragment"])]);
`

$3

Converts a DOM node into a virtual node. Especially good for patching over pre-existing,
server-side generated HTML content.

`mjs
import {
init,
styleModule,
attributesModule,
h,
toVNode
} from "snabbdom";

const patch = init([
// Initialize a patch function with the modules used by toVNode
attributesModule // handles attributes from the DOM node
datasetModule, // handles data-* attributes from the DOM node
]);

const newVNode = h("div", { style: { color: "#000" } }, [
h("h1", "Headline"),
h("p", "A paragraph"),
h("img", { attrs: { src: "sunrise.png", alt: "morning sunrise" } })
]);

patch(toVNode(document.querySelector(".container")), newVNode);
`

$3

Hooks are a way to hook into the lifecycle of DOM nodes. Snabbdom
offers a rich selection of hooks. Hooks are used both by modules to
extend Snabbdom, and in normal code for executing arbitrary code at
desired points in the life of a virtual node.

#### Overview

| Name | Triggered when | Arguments to callback |
| ----------- | -------------------------------------------------- | ----------------------- |
| pre | the patch process begins | none |
| init | a vnode has been added | vnode |
| create | a DOM element has been created based on a vnode | emptyVnode, vnode |
| insert | an element has been inserted into the DOM | vnode |
| prepatch | an element is about to be patched | oldVnode, vnode |
| update | an element is being updated | oldVnode, vnode |
| postpatch | an element has been patched | oldVnode, vnode |
| destroy | an element is directly or indirectly being removed | vnode |
| remove | an element is directly being removed from the DOM | vnode, removeCallback |
| post | the patch process is done | none |

The following hooks are available for modules: pre, create,
update, destroy, remove, post.

The following hooks are available in the hook property of individual
elements: init, create, insert, prepatch, update,
postpatch, destroy, remove.

#### Usage

To use hooks, pass them as an object to hook field of the data
object argument.

`mjs
h("div.row", {
key: movie.rank,
hook: {
insert: (vnode) => {
movie.elmHeight = vnode.elm.offsetHeight;
}
}
});
`

#### The init hook

This hook is invoked during the patch process when a new virtual node
has been found. The hook is called before Snabbdom has processed the
node in any way. I.e., before it has created a DOM node based on the
vnode.

#### The insert hook

This hook is invoked once the DOM element for a vnode has been
inserted into the document _and_ the rest of the patch cycle is done.
This means that you can do DOM measurements (like using
getBoundingClientRect
in this hook safely, knowing that no elements will be changed
afterwards that could affect the position of the inserted elements.

#### The remove hook

Allows you to hook into the removal of an element. The hook is called
once a vnode is to be removed from the DOM. The handling function
receives both the vnode and a callback. You can control and delay the
removal with the callback. The callback should be invoked once the
hook is done doing its business, and the element will only be removed
once all remove hooks have invoked their callback.

The hook is only triggered when an element is to be removed from its
parent – not if it is the child of an element that is removed. For
that, see the destroy hook.

#### The destroy hook

This hook is invoked on a virtual node when its DOM element is removed
from the DOM or if its parent is being removed from the DOM.

To see the difference between this hook and the remove hook,
consider an example.

`mjs
const vnode1 = h("div", [h("div", [h("span", "Hello")])]);
const vnode2 = h("div", []);
patch(container, vnode1);
patch(vnode1, vnode2);
`

Here destroy is triggered for both the inner div element _and_ the
span element it contains. remove, on the other hand, is only
triggered on the div element because it is the only element being
detached from its parent.

You can, for instance, use remove to trigger an animation when an
element is being removed and use the destroy hook to additionally
animate the disappearance of the removed element's children.

$3

Modules work by registering global listeners for hooks. A module is simply a dictionary mapping hook names to functions.

`mjs
const myModule = {
create: (oldVnode, vnode) => {
// invoked whenever a new virtual node is created
},
update: (oldVnode, vnode) => {
// invoked whenever a virtual node is updated
}
};
`

With this mechanism you can easily augment the behaviour of Snabbdom.
For demonstration, take a look at the implementations of the default
modules.

Modules documentation

This describes the core modules. All modules are optional. JSX examples assume you're using the jsx pragma provided by this library.

$3

The class module provides an easy way to dynamically toggle classes on
elements. It expects an object in the class data property. The
object should map class names to booleans that indicate whether or
not the class should stay or go on the vnode.

`mjs
h("a", { class: { active: true, selected: false } }, "Toggle");
`

In JSX, you can use class like this:

`jsx