0
# Element Creation and Manipulation
1

2
Functions for creating and manipulating virtual elements with full React compatibility, enabling seamless migration from React codebases.
3

4
## Capabilities
5

6
### createElement Function
7

8
Creates virtual DOM elements compatible with React.createElement signature.
9

10
```typescript { .api }
11
/**
12
 * Creates a virtual DOM element with React-compatible signature
13
 * @param type - Element type (string for DOM elements, function/class for components)
14
 * @param props - Element properties and attributes
15
 * @param children - Child elements (variadic arguments)
16
 * @returns VNode representing the virtual DOM element
17
 */
18
function createElement(
19
  type: string | ComponentClass<any> | Function,
20
  props?: any,
21
  ...children: any[]
22
): VNode;
23
```
24

25
**Usage Examples:**
26

27
```typescript
28
import { createElement } from "inferno-compat";
29

30
// Create DOM elements
31
const div = createElement('div', { className: 'container' }, 'Hello World');
32
const input = createElement('input', { 
33
  type: 'text', 
34
  placeholder: 'Enter text',
35
  onChange: (e) => console.log(e.target.value)
36
});
37

38
// Create component elements
39
function Welcome(props) {
40
  return createElement('h1', null, `Hello, ${props.name}!`);
41
}
42

43
const welcome = createElement(Welcome, { name: 'Alice' });
44

45
// With JSX (requires transpilation)
46
const jsx = <div className="container">Hello World</div>;
47
// Transpiles to: createElement('div', { className: 'container' }, 'Hello World')
48
```
49

50
### cloneElement Function
51

52
Clones virtual DOM elements with optional property and children modifications.
53

54
```typescript { .api }
55
/**
56
 * Clones a virtual DOM element with optional modifications
57
 * @param element - VNode to clone
58
 * @param props - Additional or override properties
59
 * @param children - Replacement children (variadic arguments)
60
 * @returns New VNode with modifications applied
61
 */
62
function cloneElement(element: VNode, props?: any, ...children: any[]): VNode;
63
```
64

65
**Usage Examples:**
66

67
```typescript
68
import { createElement, cloneElement } from "inferno-compat";
69

70
const original = createElement('button', { 
71
  className: 'btn', 
72
  onClick: () => console.log('clicked') 
73
}, 'Click me');
74

75
// Clone with additional class
76
const modified = cloneElement(original, { 
77
  className: 'btn btn-primary' 
78
});
79

80
// Clone with new children
81
const withNewText = cloneElement(original, {}, 'New Text');
82

83
// Clone in component for prop injection
84
function ButtonWrapper({ children, ...props }) {
85
  return children.map(child => 
86
    cloneElement(child, { 
87
      ...props, 
88
      className: `${child.props.className || ''} wrapper-style`.trim()
89
    })
90
  );
91
}
92
```
93

94
### isValidElement Function
95

96
Checks if an object is a valid Inferno/React element.
97

98
```typescript { .api }
99
/**
100
 * Determines if an object is a valid virtual DOM element
101
 * @param obj - Object to test
102
 * @returns true if object is a valid VNode/element
103
 */
104
function isValidElement(obj: any): boolean;
105
```
106

107
**Usage Examples:**
108

109
```typescript
110
import { createElement, isValidElement } from "inferno-compat";
111

112
const element = createElement('div', null, 'Hello');
113
const notElement = { type: 'div', props: {} };
114

115
console.log(isValidElement(element));    // true
116
console.log(isValidElement(notElement)); // false
117
console.log(isValidElement('string'));   // false
118
console.log(isValidElement(null));       // false
119

120
// Use in component validation
121
function renderChildren(children) {
122
  return children.filter(child => 
123
    isValidElement(child) || typeof child === 'string' || typeof child === 'number'
124
  );
125
}
126
```
127

128
### createFactory Function
129

130
Creates a factory function for creating elements of a specific type.
131

132
```typescript { .api }
133
/**
134
 * Creates a factory function for a specific element type
135
 * @param type - Element type to create factory for
136
 * @returns Factory function that creates elements of the specified type
137
 */
138
function createFactory(
139
  type: string | ComponentClass<any> | Function
140
): (...children: any[]) => VNode;
141
```
142

143
**Usage Examples:**
144

145
```typescript
146
import { createFactory } from "inferno-compat";
147

148
// Create factories for common elements
149
const div = createFactory('div');
150
const button = createFactory('button');
151
const span = createFactory('span');
152

153
// Use factories to create elements
154
const container = div({ className: 'container' },
155
  button({ onClick: () => alert('Hello') }, 'Click me'),
156
  span(null, 'Some text')
157
);
158

159
// Component factory
160
function CustomButton(props) {
161
  return button({ 
162
    className: 'custom-btn',
163
    ...props 
164
  }, props.children);
165
}
166

167
const customButtonFactory = createFactory(CustomButton);
168
const myButton = customButtonFactory({ onClick: handleClick }, 'Custom Button');
169

170
// Legacy React patterns
171
const DOM = {
172
  div: createFactory('div'),
173
  span: createFactory('span'),
174
  button: createFactory('button'),
175
  input: createFactory('input'),
176
  form: createFactory('form')
177
};
178

179
const form = DOM.form({ onSubmit: handleSubmit },
180
  DOM.input({ type: 'text', name: 'username' }),
181
  DOM.button({ type: 'submit' }, 'Submit')
182
);
183
```
184

185
### React Compatibility Features
186

187
Element creation functions include several React-specific compatibility features:
188

189
#### Property Mapping
190
- **htmlFor → for**: React's htmlFor attribute is mapped to HTML for attribute
191
- **className → class**: React's className is converted to HTML class attribute  
192
- **onDoubleClick → onDblClick**: Event handler normalization
193
- **SVG attributes**: Automatic camelCase to hyphen-case conversion for SVG properties
194

195
#### Style Processing
196
- **camelCase conversion**: React-style camelCase CSS properties converted to hyphen-case
197
- **Number units**: Automatic 'px' suffix addition for numeric CSS values (except unitless properties)
198
- **Vendor prefixes**: Proper handling of vendor-prefixed CSS properties
199

200
#### Event Handling
201
- **SyntheticEvent compatibility**: Event objects include persist() method for React compatibility
202
- **onChange transformation**: React's onChange events are converted to appropriate native events (onInput for text inputs)
203
- **Event pooling**: Compatible with React's event pooling patterns
204

205
#### Children Processing
206
- **Iterable children**: Support for iterable data structures as children (Map, Set, etc.)
207
- **Fragment flattening**: Automatic flattening of nested arrays and fragments
208
- **Key preservation**: Proper key handling for list reconciliation
209

210
### Element Types
211

212
The createElement function supports multiple element types:
213

214
- **HTML elements**: Strings like 'div', 'span', 'button'
215
- **SVG elements**: SVG-specific elements with proper attribute handling
216
- **Function components**: Pure functions that return virtual DOM
217
- **Class components**: ES6 classes extending Component or PureComponent
218
- **Forward ref components**: Components created with forwardRef
219
- **Fragment**: Special fragment type for grouping elements