repository·main·Indexed 22 days ago
https://github.com/taoqf/node-html-parserA high-performance HTML parser for Node.js that generates a simplified DOM tree. It provides basic element query support via querySelector and querySelectorAll, DOM traversal, and manipulation of HTMLElement attributes and class lists. Version 9.0.1 supports TypeScript ^4.1.2 and includes utilities for validating HTML and configuring parsing behavior such as handling void tags and nested elements.
You can use parse to generate a simplified DOM tree from an HTML string. The parse() method wraps the input in a new node, meaning the first node of your input data will be the firstChild of the returned root node.
Supported environments:
import { parse } from 'node-html-parser';var HTMLParser = require('node-html-parser');Install the package using npm to get started with fast HTML parsing.
npm install --save node-html-parserNote for TypeScript users: The minimum supported TypeScript version is ^4.1.2.
The parse(data, options) method parses the provided HTML string and returns the root of the generated DOM.
Options object schema:
{
lowerCaseTagName: false, // convert tag name to lower case (hurts performance heavily)
comment: false, // retrieve comments (hurts performance slightly)
fixNestedATags: false, // fix invalid nested <a> HTML tags
parseNoneClosedTags: false, // close none closed HTML tags instead of removing them
preserveTagNesting: false, // preserve invalid HTML nesting instead of auto-closing tags (e.g. <p><p>bar</p></p>)
voidTag: {
tags: ['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'param', 'source', 'track', 'wbr'], // default list
closingSlash: true // add a final slash <br/> during serialization
},
blockTextElements: {
script: true, // keep text content when parsing
noscript: true,
style: true,
pre: true
},
closeAllByClosing: false // Close all non-closed tags when containing element closes
}valid(data, options) to check if the provided HTML string is valid. It returns true if valid and false otherwise.Navigate between nodes using the following properties and methods:
Navigation Properties:
firstChild / lastChild: The first/last child Node.firstElementChild / lastElementChild: The first/last child HTMLElement.nextSibling / previousSibling: The next/previous Node in the parent's child list.nextElementSibling / previousElementSibling: The next/previous HTMLElement in the parent's child list.childNodes: All child nodes (Text, Comment, or HTMLElement).children: Only child HTMLElements.Traversal Methods:
closest(selector): Returns the closest ancestor (including itself) that matches the CSS selector, or null.Retrieve text content using these properties:
text: Returns unescaped text (similar to innerText). Note: This is slow on the first call.rawText: Returns escaped text as-is (e.g., including &). This is fast.textContent: Returns the text content of the element and its descendants. Efficient for both getting and setting.structuredText: Returns structured text.innerText: (Inherited concept) via text property.Use CSS selectors to find elements within the DOM tree.
querySelector(selector): Returns the first matching HTMLElement. Returns null if no match is found.querySelectorAll(selector): Returns an array of all matching Node objects. Supports full CSS3 selectors (since v3.0.0).The classList property provides a ClassList object to manage an element's CSS classes.
Available methods:
add(c): Add a class name.replace(old, new): Replace an existing class name.remove(c): Remove a class name.toggle(c): Toggle a class (adds if missing, removes if present).contains(c): Returns true if the class exists.value: Returns the current class names as a string.length: Returns the number of classes.Use these methods to change the state of an HTMLElement:
Attributes:
setAttribute(key, value): Sets the attribute.setAttributes(Record<string, string>): Sets multiple attributes at once.removeAttribute(key): Removes an attribute.getAttribute(key): Returns the attribute value or undefined if not set.Content:
set_content(content): Sets content using a string, a Node, or an array of Nodes. Warning: Do not use this on the root node.textContent: Get or set the text content (more efficient than set_content).innerHTML / outerHTML: Get or set the HTML string representation.When using parse() (or base_parse), you can pass an Options object to control the parser behavior:
lowerCaseTagName (boolean): If true, tag names will be converted to lowercase.comment (boolean): If true, HTML comments will be preserved in the tree.fixNestedATags (boolean): If true, prevents nested <a> tags by terminating the previous <a> tag when a new one is encountered.parseNoneClosedTags (boolean): Controls how non-closed tags are handled.preserveTagNesting (boolean): If true, preserves invalid HTML nesting (e.g., <p><p>bar</p></p>) instead of auto-closing tags.blockTextElements (object): A map of tag names to booleans. Tags marked true will be treated as elements that block text (like <script> or <style>).voidTag (object): Configuration for void elements.tags (string[]): Custom list of void tags.closingSlash (boolean): If true, serializes void tags with a trailing slash (e.g., <br/>).parse function takes an HTML string and returns the root HTMLElement. It handles the construction of the DOM tree, including resolving unclosed tags and managing parent-child relationships. If the HTML is malformed, the parser uses internal heuristics to attempt to create a valid tree structure based on the provided options.The parse function is the primary entrypoint for converting an HTML string into a searchable DOM tree. It accepts the HTML data as a string and an optional options object of type Options to configure parsing behavior.
import parse from 'node-html-parser';
const html = '<div><p>Hello World</p></div>';
const dom = parse(html);
// Accessing elements
const p = dom.querySelector('p');
console.log(p.text);