Guide · Open source

How to use virtual-dom: render, diff and patch a DOM tree

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

virtual-dom is a JavaScript library for describing what a page should look like as a lightweight tree of plain JavaScript objects, called a VTree. When your app state changes, you build a new tree, and the library diffs it against the previous one and patches only the parts of the real browser DOM that changed. This guide explains the three core steps (element creation, diff computation and patch operations), shows the README's example, and covers who the library suits and who should choose something else.

virtual-domMatt-Esch/virtual-dom · ★ 11.8k · MIT Install options & downloads

Quick start

1Clone the repository. Run the README's clone command to get the source. Check Node.js is installed, since the README lists it as a prerequisite without a version.
2Write a render function. Create a function that takes your app state and returns a tree built with h(), describing the DOM you want.
3Create the first DOM node. Call createElement on the first tree and append the resulting node to the document.
4Diff the old and new trees. When state changes, build a new tree and call diff(previous, current) to get the patch object.
5Apply the patches. Call patch(rootNode, patches), keep the returned root node, and store the new tree as the previous one for the next update.

What problem does virtual-dom solve?

Manual DOM manipulation is messy, and keeping track of the previous DOM state is hard. The README's approach is to write your code as if you were recreating the entire DOM whenever state changes. Recreating the whole DOM for real on every change would be slow and could make input fields lose focus, so virtual-dom works out the minimal set of changes for you.

You describe the view you want as a VTree. virtual-dom then figures out how to make the DOM match it without recreating all of the DOM nodes.

Install virtual-dom and set up Node.js

The project lists Node.js as a prerequisite, but the README does not state which Node.js version is required. The README's install command is to clone the repository from GitHub. The example code in the README loads modules with require('virtual-dom/h') and similar paths, so you will use it as a JavaScript package in your project.

Check the repository for current packaging instructions, since the README gives only the clone command.

Prerequisite: Node.js (version not stated in the README)
Clone command from the README: git clone https://github.com/Matt-Esch/virtual-dom

git clone https://github.com/Matt-Esch/virtual-dom

Build a VTree with h() or the VNode objects

A VTree is a tree of plain JavaScript objects that mirrors the DOM you want. You can build it in two ways. The verbose way uses the VNode and VText objects directly. The terse way uses virtual-hyperscript, through the h function.

The README notes that a VTree is designed to be equivalent to an immutable data structure. The functions that take VTrees never mutate them, so you can reuse nodes in several places.

Verbose: new VNode(tag, properties, children) with new VText(text)
Terse: h('.greeting', ['Hello ' + data.name]) using virtual-hyperscript

var h = require('virtual-dom/h');

function render(data) {
    return h('.greeting', ['Hello ' + data.name]);
}

module.exports = render;

Create, diff and patch the DOM in a working example

The README example follows three steps. First, a render function declares what the DOM should look like for a given count. Second, the document is initialised: build the first tree, create a root DOM node from it with createElement, and append it to the page. Third, on each update, build a new tree, compute the patches with diff(previous, current), apply them with patch(rootNode, patches), and store the new tree as the previous one.

The example updates once per second with setInterval. The README links to a live version on RequireBin.

createElement(tree) returns a DOM node, used once for the first render
diff(previous, current) returns a patch object describing the changes
patch(rootNode, patches) applies the patches and returns the new root node

var h = require('virtual-dom/h');
var diff = require('virtual-dom/diff');
var patch = require('virtual-dom/patch');
var createElement = require('virtual-dom/create-element');

function render(count)  {
    return h('div', {
        style: {
            textAlign: 'center',
            lineHeight: (100 + count) + 'px',
            border: '1px solid red',
            width: (100 + count) + 'px',
            height: (100 + count) + 'px'
        }
    }, [String(count)]);
}

var count = 0;

var tree = render(count);
var rootNode = createElement(tree);
document.body.appendChild(rootNode);

setInterval(function () {
      count++;

      var newTree = render(count);
      var patches = diff(tree, newTree);
      rootNode = patch(rootNode, patches);
      tree = newTree;
}, 1000);

Where to find module documentation

The README splits documentation by component. create-element.js and patch.js are documented in the vdom README, diff.js in the vtree README, and h.js in the virtual-hyperscript README. Type signatures are in a separate javascript signature definition file, docs.jsig.

The README also lists tools for converting existing HTML into hyperscript: html2hscript, html2hyperscript, and an online converter.

create-element.js and patch.js: vdom README
diff.js: vtree README
h.js: virtual-hyperscript README
Type signatures: docs.jsig
HTML to hyperscript: html2hscript, html2hyperscript

Know the limits before you adopt it

The README labels the project experimental, and the last push shown is January 2023. It handles rendering only. It provides no routing, state management or components, so you must build those yourself or bring other libraries. The README does not describe current framework integrations.

Because of this, virtual-dom suits learning, small rendering cores and existing codebases that already use its APIs. Teams that need a production-proven, actively maintained choice should look at the alternatives.

Experimental stability label in the README
No routing, state management or components
Last push shown: January 2023

What people use it for

Building a custom rendering layer for your own web app
Learning how virtual DOM diffing and patching work, using the README example
Maintaining existing code that already uses the virtual-dom or virtual-hyperscript APIs
Adding a small declarative rendering core to a project that does not want a full framework

Frequently asked questions

Is virtual-dom free to use?

Yes. The repository is listed under the MIT licence, which permits use in commercial and private projects. Check the licence file in the repository for the exact terms.

What are the requirements to use virtual-dom?

The listed prerequisite is Node.js. The README does not state which Node.js version is needed, so check the project for that detail before you start.

How do I install virtual-dom?

The README's install command is git clone https://github.com/Matt-Esch/virtual-dom. The README does not give a separate package-manager command, so check the repository for current packaging instructions.

Is virtual-dom a full front-end framework?

No. It only handles rendering: building trees, diffing them and patching the DOM. It has no routing, state management or components, according to the README.

What are the alternatives to virtual-dom?

Comparable projects listed for this item are React, Preact, Snabbdom and Inferno. React and Preact are full ecosystems, while Snabbdom is a closer match for a small virtual DOM library. Pick based on whether you need a complete framework or only a rendering core.

Why is my virtual-dom code not updating the page?

The README does not include a troubleshooting section. Check that you store the tree returned by your render function as the previous tree and that you keep the root node returned by patch, as the README example does. The module documentation in the vdom and vtree READMEs covers the individual functions.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use virtual-dom if you are a JavaScript developer building your own rendering layer, want to learn how diffing and patching work, or maintain code that already uses its APIs. Pick a framework such as React or Preact if you need routing, components, a production-proven track record or a widely supported ecosystem, since the README labels virtual-dom experimental.

Install options & downloads