Snabbdom: the module list, the patch contract, and the missing unmount call
A virtual DOM library with focus on simplicity, modularity, powerful features and performance.
At a glance
- What is it?
- Snabbdom keeps a virtual DOM core at about 200 source lines and pushes everything else into modules you pass to init. The trade is visible in the API: patch accepts a DOM element initially or a previously returned vnode, there is no unmount call, and server-side HTML output belongs to a separate package.
- Who is it for?
- Pick Snabbdom if you want to choose exactly which DOM behaviours exist in your application and you are prepared to assemble them, because the core is about 200 source lines and each capability arrives as a module you name in init. Avoid it if you want server-side HTML out of the box, since snabbdom-to-html is a third-party package, or if you want an API that can unmount a tree, because the guide to doing that is to patch in a comment vnode.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 151 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- snabbdom/snabbdom12,385 ★ · -8
| Repository | 2026-09-22 | 2026-11-15 |
|---|---|---|
| snabbdom/snabbdom | 12.4k | 12.4k |
-8 Stars in the last 54 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Install from npm, and init hands back a patch function that does nothing yet
The package is published to npm as `snabbdom`, and the README's npm badge points at its npm registry page. Three fields in package.json decide what you are installing. `files` is `build`, `main` is `build/index.js`, `types` is `build/index.d.ts`, and `type` is `module`, so what you consume is ESM output from a TypeScript source tree, not a bundled CommonJS file. The `engines` field asks for node `>=12.17.0` and `sideEffects` is `false`, which is what lets a bundler drop the modules you never import. Your first real use is two calls. `init` takes a list of modules and returns the `patch` function that uses them:
import { init, classModule, styleModule } from "snabbdom";
const patch = init([classModule, styleModule]);and `patch` takes the current view and the new one:
patch(oldVnode, newVnode);The first argument is a DOM element or a vnode, the second is the new vnode. Pass a DOM element with a parent and it gets replaced by a node built from your vnode.
patch only accepts an old vnode it returned from a previous patch
This is the constraint that decides how you structure state. Any old vnode you pass must be the resulting vnode from a previous call to patch, because Snabbdom stores information inside the vnode. You cannot reconstruct a fresh old tree to pass in. The design has a stated reason: keeping the old state in the vnode avoids creating a new old vnode tree on every patch, which is cheaper and simpler. The cost is that the view becomes something you thread through your program rather than something you can derive from state at will. The patch signature is equivalent to a reduce or scan function, which the README says allows easier integration with a FRP library.
There is no unmount call, so the guide is to patch in a comment vnode
The unmounting section is short and admits its own hedge. There is no API specifically for removing a vnode tree from its mount point element, and the offered workaround is providing a comment vnode as the second argument to patch, which the README describes as almost achieving this. Take the word almost seriously. Your teardown path is code you write on top of a diff, not a documented lifecycle method, and if your application never calls patch with that comment vnode the tree stays mounted. If your framework builds on Snabbdom, this is the gap you inherit: unmounting is your problem, not the library's.
Four hooks fire, and each can be set per vnode or once per module
The README's table of contents has sections for the `init`, `insert`, `remove` and `destroy` hooks. Each one can be attached to an individual vnode, and each module can also carry a global version that applies to everything it touches, which is what the README means by hooks available both per vnode and globally for modules to hook into any part of the diff and patch process. This is the extension seam for metrics, logging, or anything that needs to observe mutation rather than describe it. The same breadth is the trap. A global hook runs on every node the module touches.. Decide early which hooks are per vnode and which belong to the module.
The module list decides whether your attributes do anything
Read the feature list carefully and it is mostly a list of modules. The `h` helper for creating nodes, SVG support that the README says just works with the `h` helper, features for complex CSS animations, powerful event listener functionality, thunks for optimising diff and patch further, and JSX support including TypeScript types. The DOM behaviors supplied by modules require those modules in the array passed to init; helpers such as `h` are imported separately. Six modules are documented: the class module, the props module, the attributes module, the dataset module, the style module and the eventlisteners module. The style module has its own subsections for custom properties, which are CSS variables, delayed properties, and setting properties on remove and on destroy. If you leave a module out, its features are not available.
A vnode holds six fields, and key is a string or a number
The vnode reference in the README lists sel as a string, data as an object, children as an array of vnodes, text as a string, elm as an Element, and key as a string or a number. `elm` is the giveaway. A description of markup would not need a field pointing back at the live DOM node, so the vnode is bookkeeping as much as it is markup, which is the same fact that makes the patch contract above unavoidable. `key` is the field that lets the diff decide that this element is the same element as last time rather than a new one, so its type matters: the documentation accepts a string or a number and nothing more. A `fragment` helper exists in the table of contents and is marked experimental, so check its status in the release notes before you build on it.
tsc builds it, a browser runs the tests, and test:watch misses .ts files
The scripts section is where the toolchain shows. The build is `tsc && ts-add-js-extension --dir=build`, and the test script chains all three stages:
npm run build && npm run lint && npm run unitLint is `eslint .` with a flat `eslint.config.mjs` at the top level, and the unit script is `web-test-runner` over `test/unit/*.{ts,tsx}` with `--node-resolve` and `--coverage`, configured by `web-test-runner.config.js`. Browser coverage is not incidental: `@web/test-runner-browserstack` is a dev dependency, `browserstack-browsers.js` sits at the top level, and the README thanks Browserstack for cross-browser testing tools. Which means unit tests execute in browsers.. Read `test:watch` closely too: its glob is `test/unit/*.{tsx,tsx}`, so the extension before the comma is missing and your `.ts` unit tests never run in watch mode. The one-shot `unit` script has the correct `{ts,tsx}` pair.
3.6.4 shipped on 2026-06-17, and server-side HTML lives in another package
The release history is uneven. v3.6.4 was published on 2026-06-17, v3.6.3 on 2025-09-30, v3.6.2 on 2024-01-31, and the last push to the master branch was on 2026-06-17, matching the newest tag. Read that as a project that moves in deliberate steps rather than on a schedule, which suits a small core and makes upstream dependency review cheap. The feature you will look for first is not here. Server-side HTML output is listed under third-party features and comes from snabbdom-to-html; compact vnode creation from snabbdom-helpers; template string support from snabby; and vnode assertion from snabbdom-looks-like. Snabbdom itself renders in a browser, so a server-rendered route means adopting a separate package and its version.
Editorial conclusion
Pick Snabbdom if you want to choose exactly which DOM behaviours exist in your application and you are prepared to assemble them, because the core is about 200 source lines and each capability arrives as a module you name in init. Avoid it if you want server-side HTML out of the box, since snabbdom-to-html is a third-party package, or if you want an API that can unmount a tree, because the guide to doing that is to patch in a comment vnode. Before you commit, check two things in package.json: that your build can consume an ESM-only package, given the type field and a build/index.js entry point, and whether the module list you need, classModule, propsModule, styleModule and eventListenersModule, is short enough that you can hold it in your head.
Frequently asked questions
How do I install and start using Snabbdom?
Snabbdom is published to npm as snabbdom, with main set to build/index.js and types to build/index.d.ts. It is ESM, with type set to module, and it asks for node >=12.17.0. The first call is init with the modules you want, which returns the patch function you then call with the current and the new vnode.
How do I unmount a Snabbdom tree?
There is no API specifically for removing a vnode tree from its mount point element. The workaround the README describes is passing a comment vnode as the second argument to patch, which it says almost achieves removal.
Which Snabbdom modules do I need for classes, styles and events?
The documented modules are the class, props, attributes, dataset, style and eventlisteners modules. The style module covers custom properties as CSS variables, delayed properties, and setting properties on remove and on destroy. A module's features are available only if it is in the array passed to init, so pass every one whose features you use.
Does Snabbdom support JSX and TypeScript?
The table of contents has a JSX section with subsections for TypeScript and Babel, and the feature list names JSX support including TypeScript types. The repository's primary language is TypeScript and the package ships build/index.d.ts as its types entry point.
Can Snabbdom render HTML on the server?
Not on its own. Server-side HTML output is listed as a third-party feature provided by snabbdom-to-html. Compact vnode creation comes from snabbdom-helpers, template strings from snabby, and vnode assertion from snabbdom-looks-like.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/snabbdom-snabbdom)Star history chart for your README
[](https://hysenlabs.com/projects/snabbdom-snabbdom)Was this useful?