<img alt="Snabbdom" src="logo.png" width="356px">
A virtual DOM library with focus on simplicity, modularity, powerful features
and performance.
* * *
[![License: MIT](https://img.shields.io/badge/License-MIT-brightgreen.svg)](https://opensource.org/licenses/MIT)
[![Build Status](https://travis-ci.org/snabbdom/snabbdom.svg?branch=master)](https://travis-ci.org/snabbdom/snabbdom)
[![npm version](https://badge.fury.io/js/snabbdom.svg)](https://badge.fury.io/js/snabbdom)
[![npm downloads](https://img.shields.io/npm/dm/snabbdom.svg)](https://www.npmjs.com/package/snabbdom)
[![Join the chat at https://gitter.im/paldepind/snabbdom](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/paldepind/snabbdom?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
Thanks to [Browserstack](https://www.browserstack.com/) for providing access to
their great cross-browser testing tools.
## 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 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](#svg).
* Features for doing complex CSS animations.
* Powerful event listener functionality.
* [Thunks](#thunks) to optimize the diff and patch process even further.
* Third party features
* JSX support thanks to [snabbdom-pragma](https://github.com/Swizz/snabbdom-pragma).
* Server-side HTML output provided by [snabbdom-to-html](https://github.com/acstll/snabbdom-to-html).
* Compact virtual DOM creation with [snabbdom-helpers](https://github.com/krainboltgreene/snabbdom-helpers).
* Template string support using [snabby](https://github.com/jamen/snabby).
* Virtual DOM assertion with [snabbdom-looks-like](https://github.com/jvanbruegge/snabbdom-looks-like)
## Example
```javascript
var snabbdom = require('snabbdom');
var patch = snabbdom.init([ // Init patch function with chosen modules
require('snabbdom/modules/class').default, // makes it easy to toggle classes
require('snabbdom/modules/props').default, // for setting properties on DOM elements
require('snabbdom/modules/style').default, // handles styling on elements with support for animations
require('snabbdom/modules/eventlisteners').default, // attaches event listeners
]);
var h = require('snabbdom/h').default; // helper function for creating vnodes
var container = document.getElementById('container');
var vnode = h('div#container.two.classes', {on: {click: someFn}}, [
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);
var newVnode = h('div#container.two.classes', {on: {click: anotherEventHandler}}, [
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
// to unmount from the DOM and clean up, simply pass null
patch(newVnode, null)
```
## More examples
* [Animated reordering of elements](http://snabbdom.github.io/snabbdom/examples/reorder-animation/)
* [Hero transitions](http://snabbdom.github.io/snabbdom/examples/hero/)
* [SVG Carousel](http://snabbdom.github.io/snabbdom/examples/carousel-svg/)
* * *
## Table of contents
* [Core documentation](#core-documentation)
* [`snabbdom.init`](#snabbdominit)
* [`patch`](#patch)
* [`snabbdom/h`](#snabbdomh)
* [`snabbdom/tovnode`](#snabbdomtovnode)
* [Hooks](#hooks)
* [Overview](#overview)
* [Usage](#usage)
* [The `init` hook](#the-init-hook)
* [The `insert` hook](#the-insert-hook)
* [The `remove` hook](#the-remove-hook)
* [The `destroy` hook](#the-destroy-hook)
* [Creating modules](#creating-modules)
* [Modules documentation](#modules-documentation)
* [The class module](#the-class-module)
* [The props module](#the-props-module)
* [The attributes module](#the-attributes-module)
* [The dataset module](#the-dataset-module)
* [The style module](#the-style-module)
* [Custom properties (CSS variables)](#custom-properties-css-variables)
* [Delayed properties](#delayed-properties)
* [Set properties on `remove`](#set-properties-on-remove)
* [Set properties on `destroy`](#set-properties-on-destroy)
* [Eventlisteners module](#eventlisteners-module)
* [SVG](#svg)
* [Classes in SVG Elements](#classes-in-svg-elements)
* [Thunks](#thunks)
* [Virtual Node](#virtual-node)
* [sel : String](#sel--string)
* [data : Object](#data--object)
* [children : Array<vnode>](#children--arrayvnode)
* [text : string](#text--string)
* [elm : Element](#elm--element)
* [key : string | number](#key--string--number)
* [Structuring applications](#structuring-applications)
* [Common errors](#common-errors)
* [Maintenance policy](#maintenance-policy)
* [Pull requests](#pull-requests)
* [Releases](#releases)
## 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.
### `snabbdom.init`
The core exposes only one single function `snabbdom.init`. This `init`
takes a list of modules and returns a `patch` function that uses the
specified set of modules.
```javascript
var patch = snabbdom.init([
require('snabbdom/modules/class').default,
require('snabbdom/modules/style').default,
]);
```
### `patch`
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.
```javascript
patch(oldVnode, newVnode);
```
### `snabbdom/h`
It is recommended that you use `snabbdom/h` to create vnodes. `h` accepts a
tag/selector as a string, an optional data object and an optional string or
array of children.
```javascript
var h = require('snabbdom/h').default;
var vnode = h('div', {style: {color: '#000'}}, [
h('h1', 'Headline'),
h('p', 'A paragraph'),
]);
`