0
# DOM Elements
1

2
Complete HTMLElement implementation providing web-standard DOM manipulation APIs, content modification methods, and comprehensive property access for building and modifying HTML structures programmatically.
3

4
## Capabilities
5

6
### HTMLElement Class
7

8
Main DOM element class extending Node with complete element manipulation capabilities.
9

10
```typescript { .api }
11
class HTMLElement extends Node {
12
  // Core properties
13
  rawTagName: string;
14
  id: string;
15
  classList: DOMTokenList;
16
  rawAttrs: string;
17
  nodeType: NodeType.ELEMENT_NODE;
18
  
19
  // Inherited from Node
20
  childNodes: Node[];
21
  parentNode: HTMLElement | null;
22
  range: readonly [number, number];
23
}
24
```
25

26
### Tag and Element Information
27

28
Properties for accessing element identification and type information.
29

30
```typescript { .api }
31
/** Get/set uppercase tag name */
32
get tagName(): string;
33
set tagName(newname: string): void;
34

35
/** Get lowercase tag name */
36
get localName(): string;
37

38
/** Check if element is a void element (self-closing) */
39
get isVoidElement(): boolean;
40
```
41

42
**Usage Examples:**
43

44
```typescript
45
import { parse } from "node-html-parser";
46

47
const element = parse('<DIV>content</DIV>').firstChild as HTMLElement;
48

49
console.log(element.tagName);     // "DIV"
50
console.log(element.localName);   // "div"
51
console.log(element.isVoidElement); // false
52

53
// Change tag name
54
element.tagName = 'SPAN';
55
console.log(element.toString()); // "<span>content</span>"
56
```
57

58
### Content Properties
59

60
Properties for accessing and modifying element text and HTML content.
61

62
```typescript { .api }
63
/** Get raw text content including HTML entities */
64
get rawText(): string;
65

66
/** Get raw text content (alias for rawText) */
67
get innerText(): string;
68

69
/** Get/set decoded text content */
70
get textContent(): string;
71
set textContent(val: string): void;
72

73
/** Get decoded text content (alias for textContent) */
74
get text(): string;
75

76
/** Get formatted text with block structure and whitespace normalization */
77
get structuredText(): string;
78

79
/** Get/set inner HTML content */
80
get innerHTML(): string;
81
set innerHTML(content: string): void;
82

83
/** Get complete element HTML including tag */
84
get outerHTML(): string;
85
```
86

87
**Usage Examples:**
88

89
```typescript
90
const element = parse('<div>Hello <em>world</em>!</div>');
91

92
console.log(element.text);           // "Hello world!"
93
console.log(element.innerHTML);      // "Hello <em>world</em>!"
94
console.log(element.outerHTML);      // "<div>Hello <em>world</em>!</div>"
95

96
// Modify content
97
element.textContent = "New content";
98
console.log(element.innerHTML);      // "New content"
99

100
element.innerHTML = "<p>Paragraph</p>";
101
console.log(element.outerHTML);      // "<div><p>Paragraph</p></div>"
102
```
103

104
### Child and Sibling Navigation
105

106
Properties for navigating the DOM tree structure.
107

108
```typescript { .api }
109
/** Get all child elements (HTMLElement only, excludes text/comment nodes) */
110
get children(): HTMLElement[];
111

112
/** Get first child node of any type (element, text, comment) */
113
get firstChild(): Node | undefined;
114

115
/** Get last child node of any type (element, text, comment) */
116
get lastChild(): Node | undefined;
117

118
/** Get first child element (HTMLElement only) */
119
get firstElementChild(): HTMLElement | undefined;
120

121
/** Get last child element (HTMLElement only) */
122
get lastElementChild(): HTMLElement | undefined;
123

124
/** Get count of child elements (HTMLElement only) */
125
get childElementCount(): number;
126

127
/** Get next sibling node of any type */
128
get nextSibling(): Node | null;
129

130
/** Get previous sibling node of any type */
131
get previousSibling(): Node | null;
132

133
/** Get next sibling element (HTMLElement only) */
134
get nextElementSibling(): HTMLElement | null;
135

136
/** Get previous sibling element (HTMLElement only) */
137
get previousElementSibling(): HTMLElement | null;
138
```
139

140
**Usage Examples:**
141

142
```typescript
143
const root = parse('<div><p>First</p><span>Second</span></div>');
144

145
console.log(root.children.length);        // 2
146
console.log(root.firstElementChild.tagName); // "P"
147
console.log(root.lastElementChild.tagName);  // "SPAN"
148

149
const paragraph = root.firstElementChild;
150
console.log(paragraph.nextElementSibling.tagName); // "SPAN"
151
```
152

153
### DOM Manipulation Methods
154

155
Methods for adding, removing, and modifying child elements.
156

157
```typescript { .api }
158
/** Append a child node and return it */
159
appendChild<T extends Node = Node>(node: T): T;
160

161
/** Remove a child node */
162
removeChild(node: Node): HTMLElement;
163

164
/** Replace a child node with another */
165
exchangeChild(oldNode: Node, newNode: Node): HTMLElement;
166

167
/** Append nodes or strings to end of children */
168
append(...insertable: NodeInsertable[]): void;
169

170
/** Prepend nodes or strings to beginning of children */
171
prepend(...insertable: NodeInsertable[]): void;
172

173
/** Insert nodes or strings before this element */
174
before(...insertable: NodeInsertable[]): void;
175

176
/** Insert nodes or strings after this element */
177
after(...insertable: NodeInsertable[]): void;
178

179
/** Replace this element with nodes or strings */
180
replaceWith(...nodes: (string | Node)[]): HTMLElement;
181
```
182

183
**Usage Examples:**
184

185
```typescript
186
const parent = parse('<div></div>');
187
const child = parse('<p>Child</p>');
188

189
// Add child
190
parent.appendChild(child);
191
console.log(parent.innerHTML); // "<p>Child</p>"
192

193
// Add multiple children
194
parent.append('<span>Text</span>', parse('<em>Emphasis</em>'));
195

196
// Insert relative to element
197
const target = parent.querySelector('p');
198
target.after('<hr>');
199
target.before('<h1>Title</h1>');
200

201
// Replace element
202
target.replaceWith('<p>New content</p>');
203
```
204

205
### Content Manipulation
206

207
Advanced methods for setting content with parsing options.
208

209
```typescript { .api }
210
/** Set content with optional parsing configuration */
211
set_content(content: string | Node | Node[], options?: Partial<Options>): HTMLElement;
212

213
/** Insert HTML at specific position relative to element */
214
insertAdjacentHTML(where: InsertPosition, html: string): HTMLElement;
215
```
216

217
**InsertPosition values:**
218
- `'beforebegin'` - Before the element
219
- `'afterbegin'` - Inside the element, before its first child
220
- `'beforeend'` - Inside the element, after its last child  
221
- `'afterend'` - After the element
222

223
**Usage Examples:**
224

225
```typescript
226
const element = parse('<div>Original</div>');
227

228
// Set content with parsing options
229
element.set_content('<p>New <em>content</em></p>', {
230
  comment: true
231
});
232

233
// Insert HTML at positions
234
element.insertAdjacentHTML('beforebegin', '<header>Header</header>');
235
element.insertAdjacentHTML('afterend', '<footer>Footer</footer>');
236
element.insertAdjacentHTML('afterbegin', '<span>Start</span>');
237
element.insertAdjacentHTML('beforeend', '<span>End</span>');
238
```
239

240
### Utility Methods
241

242
Methods for element manipulation and representation.
243

244
```typescript { .api }
245
/** Convert element to HTML string */
246
toString(): string;
247

248
/** Trim content from right using regex pattern */
249
trimRight(pattern: RegExp): HTMLElement;
250

251
/** Remove all whitespace-only text nodes */
252
removeWhitespace(): HTMLElement;
253

254
/** Get visual representation of DOM structure */
255
get structure(): string;
256

257
/** Create deep copy of element */
258
clone(): Node;
259
```
260

261
**Usage Examples:**
262

263
```typescript
264
const element = parse('<div> <p>Content</p> </div>');
265

266
// Get structure visualization
267
console.log(element.structure);
268
// div
269
//   p
270
//     #text
271

272
// Remove whitespace
273
element.removeWhitespace();
274
console.log(element.innerHTML); // "<p>Content</p>"
275

276
// Clone element
277
const copy = element.clone();
278
```
279

280
### DOMTokenList Class
281

282
Class for managing element class names with standard DOM APIs.
283

284
```typescript { .api }
285
class DOMTokenList {
286
  /** Number of classes */
287
  get length(): number;
288
  
289
  /** Array of class names */
290
  get value(): string[];
291
  
292
  /** Add class name (throws error if class contains whitespace) */
293
  add(c: string): void;
294
  
295
  /** Remove class name */
296
  remove(c: string): void;
297
  
298
  /** Replace one class with another */
299
  replace(c1: string, c2: string): void;
300
  
301
  /** Toggle class presence */
302
  toggle(c: string): void;
303
  
304
  /** Check if class exists */
305
  contains(c: string): boolean;
306
  
307
  /** Get iterator for class names */
308
  values(): IterableIterator<string>;
309
  
310
  /** Get space-separated class string */
311
  toString(): string;
312
}
313
```
314

315
**Usage Examples:**
316

317
```typescript
318
const element = parse('<div class="foo bar">Content</div>');
319

320
element.classList.add('baz');
321
element.classList.remove('foo');
322
element.classList.toggle('active');
323

324
console.log(element.classList.contains('bar')); // true
325
console.log(element.classList.length);          // 2
326
console.log(element.classList.toString());      // "bar baz"
327
```
328

329
## Type Definitions
330

331
```typescript { .api }
332
type NodeInsertable = Node | string;
333
type InsertPosition = 'beforebegin' | 'afterbegin' | 'beforeend' | 'afterend';
334
```