0
# Snabbdom
1

2
Snabbdom is a virtual DOM library with focus on simplicity, modularity, powerful features and performance. It 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.
3

4
## Package Information
5

6
- **Package Name**: snabbdom  
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install snabbdom`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  init, 
16
  h, 
17
  classModule, 
18
  propsModule, 
19
  styleModule, 
20
  eventListenersModule 
21
} from "snabbdom";
22
```
23

24
For CommonJS:
25

26
```javascript
27
const { 
28
  init, 
29
  h, 
30
  classModule, 
31
  propsModule, 
32
  styleModule, 
33
  eventListenersModule 
34
} = require("snabbdom");
35
```
36

37
## Basic Usage
38

39
```typescript
40
import {
41
  init,
42
  classModule,
43
  propsModule,  
44
  styleModule,
45
  eventListenersModule,
46
  h
47
} from "snabbdom";
48

49
// Initialize patch function with chosen modules
50
const patch = init([
51
  classModule, // makes it easy to toggle classes
52
  propsModule, // for setting properties on DOM elements
53
  styleModule, // handles styling on elements with support for animations
54
  eventListenersModule // attaches event listeners
55
]);
56

57
// Create virtual nodes
58
const vnode = h("div#container.two.classes", 
59
  { on: { click: () => console.log("div clicked") } },
60
  [
61
    h("span", { style: { fontWeight: "bold" } }, "This is bold"),
62
    " and this is just normal text",
63
    h("a", { props: { href: "/foo" } }, "I'll take you places!")
64
  ]
65
);
66

67
// Patch into DOM element
68
const container = document.getElementById("container");
69
patch(container, vnode);
70
```
71

72
## Architecture
73

74
Snabbdom is built around several key components:
75

76
- **Core Engine**: Minimal virtual DOM diffing and patching algorithm (~200 SLOC)
77
- **Module System**: Extensible architecture where functionality is delegated to modules
78
- **Virtual Nodes**: Lightweight representations of DOM elements with selector-based identity
79
- **Patch Function**: Single function interface that updates the DOM efficiently
80
- **Hook System**: Rich lifecycle hooks for both modules and individual vnodes
81

82
## Capabilities
83

84
### Core Virtual DOM
85

86
Essential functions for creating and managing virtual DOM trees, including the init function, patch function, and h helper for creating virtual nodes.
87

88
```typescript { .api }
89
function init(
90
  modules: Array<Partial<Module>>,
91
  domApi?: DOMAPI,
92
  options?: Options
93
): (oldVnode: VNode | Element | DocumentFragment, vnode: VNode) => VNode;
94

95
function h(sel: string): VNode;
96
function h(sel: string, data: VNodeData | null): VNode;
97
function h(sel: string, children: VNodeChildren): VNode;
98
function h(sel: string, data: VNodeData | null, children: VNodeChildren): VNode;
99
```
100

101
[Core Virtual DOM](./core.md)
102

103
### Modules
104

105
Six built-in modules for managing different aspects of DOM elements: attributes, classes, datasets, event listeners, properties, and styles.
106

107
```typescript { .api }
108
const attributesModule: Module;
109
const classModule: Module;
110
const datasetModule: Module;
111
const eventListenersModule: Module;
112
const propsModule: Module;
113
const styleModule: Module;
114
```
115

116
[Modules](./modules.md)
117

118
### JSX Support
119

120
JSX factory functions and TypeScript definitions for using Snabbdom with JSX syntax in React-style applications.
121

122
```typescript { .api }
123
function jsx(
124
  tag: string | FunctionComponent,
125
  data: VNodeData | null,
126
  ...children: JsxVNodeChildren[]
127
): VNode;
128

129
function Fragment(
130
  data: { key?: Key } | null,
131
  ...children: JsxVNodeChildren[]
132
): VNode;
133
```
134

135
[JSX Support](./jsx.md)
136

137
### Advanced Features
138

139
Performance optimization through thunks, comprehensive lifecycle hooks system, and helper utilities for complex use cases.
140

141
```typescript { .api }
142
function thunk(
143
  sel: string,
144
  fn: (...args: any[]) => any,
145
  args: any[]
146
): VNode;
147
function thunk(
148
  sel: string,
149
  key: any,
150
  fn: (...args: any[]) => any,
151
  args: any[]
152
): VNode;
153

154
interface Hooks {
155
  pre?: PreHook;
156
  init?: InitHook;
157
  create?: CreateHook;
158
  insert?: InsertHook;
159
  prepatch?: PrePatchHook;
160
  update?: UpdateHook;
161
  postpatch?: PostPatchHook;
162
  destroy?: DestroyHook;
163
  remove?: RemoveHook;
164
  post?: PostHook;
165
}
166
```
167

168
[Advanced Features](./advanced.md)
169

170
## Types
171

172
```typescript { .api }
173
interface VNode {
174
  sel: string | undefined;
175
  data: VNodeData | undefined;
176
  children: Array<VNode | string> | undefined;
177
  elm: Node | undefined;
178
  text: string | undefined;
179
  key: Key | undefined;
180
}
181

182
interface VNodeData<VNodeProps = Props> {
183
  props?: VNodeProps;
184
  attrs?: Attrs;
185
  class?: Classes;
186
  style?: VNodeStyle;
187
  dataset?: Dataset;
188
  on?: On;
189
  attachData?: AttachData;
190
  hook?: Hooks;
191
  key?: Key;
192
  ns?: string;
193
  fn?: () => VNode;
194
  args?: any[];
195
  is?: string;
196
  [key: string]: any;
197
}
198

199
type Key = string | number | symbol;
200

201
interface Module {
202
  pre?: PreHook;
203
  create?: CreateHook;
204
  update?: UpdateHook;
205
  destroy?: DestroyHook;
206
  remove?: RemoveHook;
207
  post?: PostHook;
208
}
209

210
interface Options {
211
  experimental?: {
212
    fragments?: boolean;
213
  };
214
}
215
```