0
# VNode Creation
1

2
Virtual node creation functions for building virtual DOM trees with performance optimizations and type safety.
3

4
## Capabilities
5

6
### Create VNode
7

8
Creates virtual DOM nodes for HTML elements and other DOM nodes.
9

10
```typescript { .api }
11
/**
12
 * Creates virtual DOM nodes for HTML elements and other DOM nodes
13
 * @param flags - VNodeFlags indicating the type and behavior of the VNode
14
 * @param type - HTML tag name or element type
15
 * @param className - CSS class name for the element
16
 * @param children - Child nodes of the element
17
 * @param childFlags - ChildFlags indicating the type of children
18
 * @param props - Properties and attributes for the element
19
 * @param key - Unique key for reconciliation
20
 * @param ref - Reference callback or object
21
 * @returns VNode representing the virtual element
22
 */
23
function createVNode<P>(
24
  flags: VNodeFlags,
25
  type: string,
26
  className?: string | null,
27
  children?: InfernoNode,
28
  childFlags?: ChildFlags,
29
  props?: Readonly<P> | null,
30
  key?: string | number | null,
31
  ref?: Ref | Refs<P> | null
32
): VNode;
33
```
34

35
**Usage Examples:**
36

37
```typescript
38
import { createVNode, VNodeFlags, ChildFlags } from "inferno";
39

40
// Simple div element
41
const div = createVNode(VNodeFlags.HtmlElement, 'div', null, 'Hello World');
42

43
// Element with props and className
44
const input = createVNode(
45
  VNodeFlags.InputElement,
46
  'input',
47
  'form-control',
48
  null,
49
  ChildFlags.HasInvalidChildren,
50
  { type: 'text', placeholder: 'Enter text' }
51
);
52

53
// Element with children
54
const list = createVNode(
55
  VNodeFlags.HtmlElement,
56
  'ul',
57
  'list',
58
  [
59
    createVNode(VNodeFlags.HtmlElement, 'li', null, 'Item 1'),
60
    createVNode(VNodeFlags.HtmlElement, 'li', null, 'Item 2')
61
  ],
62
  ChildFlags.HasKeyedChildren
63
);
64
```
65

66
### Create Component VNode
67

68
Creates VNodes for React-like components (class or functional).
69

70
```typescript { .api }
71
/**
72
 * Creates VNodes for React-like components (class or functional)
73
 * @param flags - VNodeFlags indicating the component type
74
 * @param type - Component constructor, function, or ForwardRef
75
 * @param props - Properties passed to the component
76
 * @param key - Unique key for reconciliation
77
 * @param ref - Reference callback or object
78
 * @returns VNode representing the component
79
 */
80
function createComponentVNode<P>(
81
  flags: VNodeFlags,
82
  type: Function | ComponentType<P> | Component<P, unknown> | ForwardRef<P, unknown>,
83
  props?: Readonly<P> | null,
84
  key?: null | string | number,
85
  ref?: Ref | Refs<P> | null
86
): VNode;
87
```
88

89
**Usage Examples:**
90

91
```typescript
92
import { createComponentVNode, VNodeFlags, Component } from "inferno";
93

94
// Class component
95
class MyComponent extends Component {
96
  render() {
97
    return createVNode(VNodeFlags.HtmlElement, 'div', null, this.props.message);
98
  }
99
}
100

101
const classVNode = createComponentVNode(
102
  VNodeFlags.ComponentClass,
103
  MyComponent,
104
  { message: 'Hello from class component' }
105
);
106

107
// Functional component
108
function FunctionalComponent(props) {
109
  return createVNode(VNodeFlags.HtmlElement, 'span', null, props.text);
110
}
111

112
const funcVNode = createComponentVNode(
113
  VNodeFlags.ComponentFunction,
114
  FunctionalComponent,
115
  { text: 'Hello from function' }
116
);
117
```
118

119
### Create Text VNode
120

121
Creates VNodes for text content.
122

123
```typescript { .api }
124
/**
125
 * Creates VNodes for text content
126
 * @param text - Text content (string, number, boolean, null, or undefined)
127
 * @param key - Unique key for reconciliation
128
 * @returns VNode representing the text node
129
 */
130
function createTextVNode(
131
  text?: string | boolean | null | number,
132
  key?: string | number | null
133
): VNode;
134
```
135

136
**Usage Examples:**
137

138
```typescript
139
import { createTextVNode } from "inferno";
140

141
// Simple text
142
const textNode = createTextVNode('Hello World');
143

144
// Number as text
145
const numberNode = createTextVNode(42);
146

147
// Text with key
148
const keyedText = createTextVNode('Item', 'text-1');
149

150
// Empty text (null/undefined becomes empty string)
151
const emptyText = createTextVNode(null);
152
```
153

154
### Create Fragment
155

156
Creates fragment VNodes for grouping multiple elements without a wrapper.
157

158
```typescript { .api }
159
/**
160
 * Creates fragment VNodes for grouping multiple elements without a wrapper
161
 * @param children - Array of child nodes or single child
162
 * @param childFlags - ChildFlags indicating the type of children
163
 * @param key - Unique key for reconciliation
164
 * @returns VNode representing the fragment
165
 */
166
function createFragment(
167
  children: any,
168
  childFlags: ChildFlags,
169
  key?: string | number | null
170
): VNode;
171
```
172

173
**Usage Examples:**
174

175
```typescript
176
import { createFragment, createVNode, ChildFlags, VNodeFlags } from "inferno";
177

178
// Fragment with multiple children
179
const fragment = createFragment([
180
  createVNode(VNodeFlags.HtmlElement, 'h1', null, 'Title'),
181
  createVNode(VNodeFlags.HtmlElement, 'p', null, 'Content')
182
], ChildFlags.HasNonKeyedChildren);
183

184
// Fragment with keyed children
185
const keyedFragment = createFragment([
186
  createVNode(VNodeFlags.HtmlElement, 'div', null, 'First', ChildFlags.HasInvalidChildren, null, 'div-1'),
187
  createVNode(VNodeFlags.HtmlElement, 'div', null, 'Second', ChildFlags.HasInvalidChildren, null, 'div-2')
188
], ChildFlags.HasKeyedChildren);
189
```
190

191
### Create Portal
192

193
Creates portal VNodes for rendering content outside the normal component tree.
194

195
```typescript { .api }
196
/**
197
 * Creates portal VNodes for rendering content outside the normal component tree
198
 * @param children - Content to render in the portal
199
 * @param container - DOM element where the portal content should be rendered
200
 * @returns VNode representing the portal
201
 */
202
function createPortal(children: any, container: ParentDOM): VNode;
203
```
204

205
**Usage Examples:**
206

207
```typescript
208
import { createPortal, createVNode, VNodeFlags } from "inferno";
209

210
// Portal to render modal outside component tree
211
const modal = createVNode(VNodeFlags.HtmlElement, 'div', 'modal', 'Modal content');
212
const portalVNode = createPortal(modal, document.body);
213

214
// Portal to render tooltip in specific container
215
const tooltip = createVNode(VNodeFlags.HtmlElement, 'div', 'tooltip', 'Tooltip text');
216
const tooltipPortal = createPortal(tooltip, document.getElementById('tooltip-container'));
217
```
218

219
### Direct Clone
220

221
Creates a direct clone of an existing VNode for reuse.
222

223
```typescript { .api }
224
/**
225
 * Creates a direct clone of an existing VNode for reuse
226
 * @param vNodeToClone - VNode to clone
227
 * @returns New VNode instance with same properties
228
 */
229
function directClone(vNodeToClone: VNode): VNode;
230
```
231

232
**Usage Examples:**
233

234
```typescript
235
import { directClone, createVNode, VNodeFlags } from "inferno";
236

237
// Original VNode
238
const original = createVNode(VNodeFlags.HtmlElement, 'div', 'container', 'Content');
239

240
// Clone for reuse
241
const cloned = directClone(original);
242

243
// Safe to use both in different parts of the tree
244
render(original, container1);
245
render(cloned, container2);
246
```
247

248
### Get Element VNode Flags
249

250
Determines the appropriate VNode flags for a given element type string.
251

252
```typescript { .api }
253
/**
254
 * Determines the appropriate VNode flags for a given element type string
255
 * @param type - Element type string (e.g., 'div', 'input', 'svg')
256
 * @returns VNodeFlags value corresponding to the element type
257
 */
258
function getFlagsForElementVnode(type: string): VNodeFlags;
259
```
260

261
**Usage Examples:**
262

263
```typescript
264
import { getFlagsForElementVnode, VNodeFlags } from "inferno";
265

266
// Get flags for different element types
267
const divFlags = getFlagsForElementVnode('div');        // VNodeFlags.HtmlElement
268
const inputFlags = getFlagsForElementVnode('input');    // VNodeFlags.InputElement
269
const svgFlags = getFlagsForElementVnode('svg');        // VNodeFlags.SvgElement
270
const selectFlags = getFlagsForElementVnode('select');  // VNodeFlags.SelectElement
271
const textareaFlags = getFlagsForElementVnode('textarea'); // VNodeFlags.TextareaElement
272

273
// Use with createVNode for optimized element creation
274
const vnode = createVNode(
275
  getFlagsForElementVnode('input'),
276
  'input',
277
  null,
278
  null,
279
  ChildFlags.HasNonKeyedChildren,
280
  { type: 'text', value: 'Hello' }
281
);
282
```
283

284
### Normalize Props
285

286
Normalizes a VNode's properties by moving certain props to the appropriate VNode fields.
287

288
```typescript { .api }
289
/**
290
 * Normalizes a VNode's properties by moving certain props to the appropriate VNode fields
291
 * @param vNode - VNode to normalize
292
 * @returns The same VNode with normalized properties
293
 */
294
function normalizeProps(vNode: VNode): VNode;
295
```
296

297
**Usage Examples:**
298

299
```typescript
300
import { normalizeProps, createVNode, VNodeFlags, ChildFlags } from "inferno";
301

302
// Create VNode with props that need normalization
303
const vnode = createVNode(
304
  VNodeFlags.HtmlElement,
305
  'div',
306
  null,
307
  null,
308
  ChildFlags.HasNonKeyedChildren,
309
  {
310
    className: 'my-class',
311
    children: 'Hello World'
312
  }
313
);
314

315
// Normalize props to move className and children to correct VNode fields
316
normalizeProps(vnode);
317
// vnode.className is now 'my-class'
318
// vnode.children is now 'Hello World'
319
// props.className and props.children are removed
320
```
321

322
## VNode Properties
323

324
```typescript { .api }
325
interface VNode {
326
  children: InfernoNode;
327
  childFlags: ChildFlags;
328
  dom: Element | null;
329
  className: string | null | undefined;
330
  flags: VNodeFlags;
331
  isValidated?: boolean;
332
  key: Key;
333
  props: any;
334
  ref: any;
335
  type: any;
336
}
337

338
type Key = string | number | undefined | null;
339
```
340

341
## VNode Flags
342

343
VNodeFlags are used to optimize VNode handling and indicate the type of VNode (imported from 'inferno-vnode-flags'):
344

345
- **VNodeFlags.HtmlElement**: Standard HTML elements (div, span, p, etc.)
346
- **VNodeFlags.InputElement**: Input elements with special handling
347
- **VNodeFlags.SelectElement**: Select elements with special handling
348
- **VNodeFlags.TextareaElement**: Textarea elements with special handling
349
- **VNodeFlags.SvgElement**: SVG elements
350
- **VNodeFlags.ComponentClass**: Class-based components
351
- **VNodeFlags.ComponentFunction**: Functional components
352
- **VNodeFlags.ForwardRefComponent**: Forward ref components
353
- **VNodeFlags.Fragment**: Fragment nodes
354
- **VNodeFlags.Portal**: Portal nodes
355
- **VNodeFlags.Text**: Text nodes
356

357
## Child Flags
358

359
ChildFlags optimize child handling and indicate the type of children (imported from 'inferno-vnode-flags'):
360

361
- **ChildFlags.HasInvalidChildren**: No children or invalid children
362
- **ChildFlags.HasVNodeChildren**: Single VNode child
363
- **ChildFlags.HasTextChildren**: Text-only children
364
- **ChildFlags.HasKeyedChildren**: Array of children with keys
365
- **ChildFlags.HasNonKeyedChildren**: Array of children without keys
366
- **ChildFlags.UnknownChildren**: Children need normalization
367

368
## Performance Tips
369

370
1. **Use appropriate flags**: Providing correct VNodeFlags and ChildFlags improves performance
371
2. **Provide keys**: Use keys for arrays of elements to enable efficient reconciliation
372
3. **Avoid unnecessary cloning**: Only clone VNodes when they need to be reused
373
4. **Reuse VNodes**: Clone and reuse VNodes instead of recreating identical ones