Registry / serialization / htmlparser2

htmlparser2

JSON →
library12.0.0jsnpmunverified

htmlparser2 is a high-performance, event-driven HTML/XML parser for JavaScript and TypeScript environments. It is currently at stable version 12.0.0 and maintains an active release cadence with frequent updates, often aligning with WHATWG specifications. The library prioritizes speed and efficiency, making it suitable for tasks like web scraping, content transformation, and processing RSS/Atom feeds. While fast and forgiving, it takes some shortcuts compared to strictly spec-compliant parsers like `parse5`, which might lead to different parsing results for highly malformed HTML. It integrates with an ecosystem of related packages like `domhandler` for DOM construction and `css-select` for querying.

serializationhttp-networking
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Since v11.0.0, htmlparser2 is an ESM-only module. CommonJS `require()` is no longer supported.

import { Parser } from 'htmlparser2';

A convenience function for parsing a document and returning a DOM structure using `domhandler`.

import { parseDocument } from 'htmlparser2';

Introduced in v11.0.0, this enables direct piping from Web Streams API responses.

import { WebWritableStream } from 'htmlparser2';

This quickstart demonstrates the event-driven parsing capabilities of htmlparser2 by creating a `Parser` instance and feeding it HTML content. It logs opening tags, text content, and closing tags, illustrating the callback interface.

import { Parser } from 'htmlparser2'; const htmlContent = "Xyz <script type='text/javascript'>const foo = '<<bar>>';</script><p>Hello, World!</p>"; const parser = new Parser({ onopentag(name, attributes) { console.log(`Opened tag: ${name}`); if (name === "script" && attributes.type === "text/javascript") { console.log("JavaScript block detected!"); } }, ontext(text) { // Note: This can fire at any point within text and you might // have to stitch together multiple pieces if not using a DOM handler. const trimmedText = text.trim(); if (trimmedText.length > 0) { console.log(`--> Text content: '${trimmedText}'`); } }, onclosetag(tagname) { console.log(`Closed tag: ${tagname}`); if (tagname === "script") { console.log("Script block finished."); } }, onerror(error) { console.error("Parsing error:", error); } }); parser.write(htmlContent); parser.end(); // To get a DOM, you'd typically use parseDocument with domhandler: // import { parseDocument } from 'htmlparser2'; // const dom = parseDocument('<div id="root"><span>Hi</span></div>'); // console.log(dom[0].children[0].data); // 'Hi'
Debug
Known footguns
breakingAs of v11.0.0, htmlparser2 is an ESM-only module. All CommonJS `require()` statements will fail, and you must migrate to ES Modules `import` syntax.
breakingVersion 11.0.0 raises the minimum Node.js version requirement to 20.19.0. Older Node.js environments will not be supported.
breakingVersion 12.0.0 aligns HTML parsing with the WHATWG specification, particularly for raw-text and RCDATA tags such as `<iframe>`, `<noembed>`, `<noframes>`, `<plaintext>`, and `<textarea>`. Their content is no longer parsed as HTML, and entities in `<textarea>` are now decoded.
breakingIn v9.0.0, the tokenizer's entity parsing behavior changed to align with the HTML spec, specifically for entities within attributes. This can lead to different attribute values for certain malformed inputs (e.g., `<a href='&amp=boo'>`).
breakingThe `FeedHandler` class, previously deprecated, has been completely removed in v8.0.0. Code relying on this class will break.
breakingVersion 8.0.0 requires TypeScript >= 4.5. Projects using older TypeScript versions will encounter compilation errors.
gotchahtmlparser2 is optimized for speed and may take shortcuts, meaning it is not strictly HTML spec compliant in all edge cases. For applications requiring strict spec adherence, `parse5` might be a more suitable alternative.
Upgrade
Version history

Breaking-change detection hasn't run for this library yet.

Audit
Security & dependencies

CVE tracking and dependency tree are planned for a later release.

Agent activity
0 hits · last 30 days

No traffic data recorded yet.

Resources