0
# Core Virtual DOM
1

2
Core functions for creating and managing virtual DOM trees, including initialization, patching, and virtual node creation.
3

4
## Capabilities
5

6
### Init Function
7

8
Creates a patch function configured with the specified modules and options.
9

10
```typescript { .api }
11
/**
12
 * Initialize a patch function with chosen modules
13
 * @param modules - Array of modules to include in the patch function
14
 * @param domApi - Optional DOM API implementation (defaults to htmlDomApi)
15
 * @param options - Optional configuration for experimental features
16
 * @returns Patch function for updating DOM
17
 */
18
function init(
19
  modules: Array<Partial<Module>>,
20
  domApi?: DOMAPI,
21
  options?: Options
22
): (oldVnode: VNode | Element | DocumentFragment, vnode: VNode) => VNode;
23
```
24

25
**Usage Example:**
26

27
```typescript
28
import { init, classModule, styleModule } from "snabbdom";
29

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

33
### Patch Function
34

35
The patch function returned by `init()` updates the DOM by comparing old and new virtual nodes.
36

37
```typescript { .api }
38
/**
39
 * Patch function that updates DOM based on virtual node differences
40
 * @param oldVnode - Previous virtual node, DOM element, or document fragment
41
 * @param vnode - New virtual node representing desired state
42
 * @returns The new virtual node with updated DOM references
43
 */
44
type PatchFunction = (
45
  oldVnode: VNode | Element | DocumentFragment,
46
  vnode: VNode
47
) => VNode;
48
```
49

50
**Usage Example:**
51

52
```typescript
53
const container = document.getElementById("app");
54
const vnode1 = h("div", "Hello");
55
const vnode2 = h("div", "Hello World");
56

57
// Initial render
58
const result1 = patch(container, vnode1);
59

60
// Update render
61
const result2 = patch(result1, vnode2);
62
```
63

64
### H Function
65

66
Creates virtual DOM nodes with CSS selector syntax, optional data, and children.
67

68
```typescript { .api }
69
/**
70
 * Create a virtual DOM node with selector syntax
71
 * @param sel - CSS selector string (tag, id, classes)
72
 * @returns Virtual node
73
 */
74
function h(sel: string): VNode;
75

76
/**
77
 * Create a virtual DOM node with selector and data
78
 * @param sel - CSS selector string
79
 * @param data - Virtual node data (props, attrs, etc.)
80
 * @returns Virtual node
81
 */
82
function h(sel: string, data: VNodeData | null): VNode;
83

84
/**
85
 * Create a virtual DOM node with selector and children
86
 * @param sel - CSS selector string
87
 * @param children - Child elements or text content
88
 * @returns Virtual node
89
 */
90
function h(sel: string, children: VNodeChildren): VNode;
91

92
/**
93
 * Create a virtual DOM node with selector, data, and children
94
 * @param sel - CSS selector string
95
 * @param data - Virtual node data (props, attrs, etc.)
96
 * @param children - Child elements or text content
97
 * @returns Virtual node
98
 */
99
function h(
100
  sel: string,
101
  data: VNodeData | null,
102
  children: VNodeChildren
103
): VNode;
104
```
105

106
**Usage Examples:**
107

108
```typescript
109
import { h } from "snabbdom";
110

111
// Simple element
112
const div = h("div", "Hello World");
113

114
// Element with ID and classes
115
const container = h("div#app.container.main");
116

117
// Element with properties and children
118
const button = h("button", 
119
  { 
120
    props: { type: "button" },
121
    on: { click: () => console.log("clicked") }
122
  },
123
  "Click me"
124
);
125

126
// Complex structure
127
const app = h("div.app", [
128
  h("h1", "My App"),
129
  h("p", "Welcome to Snabbdom"),
130
  h("ul", [
131
    h("li", "Item 1"),
132
    h("li", "Item 2")
133
  ])
134
]);
135
```
136

137
### Fragment Function
138

139
Creates virtual document fragments for grouping multiple elements without a wrapper (experimental feature).
140

141
```typescript { .api }
142
/**
143
 * Create a virtual document fragment (experimental)
144
 * @param children - Child elements to group in fragment
145
 * @returns Virtual node representing a document fragment
146
 */
147
function fragment(children: VNodeChildren): VNode;
148
```
149

150
**Usage Example:**
151

152
```typescript
153
import { fragment, h, init } from "snabbdom";
154

155
// Enable fragments in options
156
const patch = init([], undefined, {
157
  experimental: { fragments: true }
158
});
159

160
const fragmentNode = fragment([
161
  h("p", "First paragraph"),
162
  h("p", "Second paragraph")
163
]);
164
```
165

166
### VNode Function
167

168
Low-level virtual node creation function (typically not used directly).
169

170
```typescript { .api }
171
/**
172
 * Create a virtual node (low-level function)
173
 * @param sel - Element selector
174
 * @param data - Node data
175
 * @param children - Child nodes
176
 * @param text - Text content
177
 * @param elm - Associated DOM element
178
 * @returns Virtual node
179
 */
180
function vnode(
181
  sel: string | undefined,
182
  data: any | undefined,
183
  children: Array<VNode | string> | undefined,
184
  text: string | undefined,
185
  elm: Element | DocumentFragment | Text | undefined
186
): VNode;
187
```
188

189
### ToVNode Function
190

191
Converts existing DOM nodes to virtual nodes for integration with server-rendered content.
192

193
```typescript { .api }
194
/**
195
 * Convert a DOM node into a virtual node
196
 * @param node - DOM node to convert
197
 * @param domApi - Optional DOM API implementation
198
 * @returns Virtual node representation of the DOM node
199
 */
200
function toVNode(node: Node, domApi?: DOMAPI): VNode;
201
```
202

203
**Usage Example:**
204

205
```typescript
206
import { toVNode, init } from "snabbdom";
207

208
const patch = init([]);
209
const existingElement = document.querySelector(".server-rendered");
210
const vnode = toVNode(existingElement);
211

212
// Now you can patch over server-rendered content
213
const newVnode = h("div.updated", "New content");
214
patch(vnode, newVnode);
215
```
216

217
## Types
218

219
```typescript { .api }
220
type VNodeChildren = ArrayOrElement<VNodeChildElement>;
221
type VNodeChildElement = VNode | string | number | String | Number | undefined | null;
222
type ArrayOrElement<T> = T | T[];
223

224
interface Options {
225
  experimental?: {
226
    fragments?: boolean;
227
  };
228
}
229

230
interface DOMAPI {
231
  createElement: (tagName: any, options?: ElementCreationOptions) => HTMLElement;
232
  createElementNS: (namespaceURI: string, qualifiedName: string, options?: ElementCreationOptions) => Element;
233
  createDocumentFragment?: () => DocumentFragment;
234
  createTextNode: (text: string) => Text;
235
  createComment: (text: string) => Comment;
236
  insertBefore: (parentNode: Node, newNode: Node, referenceNode: Node | null) => void;
237
  removeChild: (node: Node, child: Node) => void;
238
  appendChild: (node: Node, child: Node) => void;
239
  parentNode: (node: Node) => Node | null;
240
  nextSibling: (node: Node) => Node | null;
241
  tagName: (elm: Element) => string;
242
  setTextContent: (node: Node, text: string | null) => void;
243
  getTextContent: (node: Node) => string | null;
244
  isElement: (node: Node) => node is Element;
245
  isText: (node: Node) => node is Text;
246
  isComment: (node: Node) => node is Comment;
247
  isDocumentFragment?: (node: Node) => node is DocumentFragment;
248
}
249
```