Parsing HTML and XML Data in Node.js
cheerio provides a jQuery-like API for server-side HTML manipulation, making it ideal for scraping and DOM traversal. htmlparser2 is a fast, streaming HTML and XML parser that emits events, serving as the engine behind Cheerio. sax is a strict, streaming XML parser focused on compliance and low-level event handling. xml2js converts XML documents into JavaScript objects, simplifying data extraction for configuration files or SOAP services.
Npm Package Weekly Downloads Trend
Github Stars Ranking
Stat Detail
Cheerio vs htmlparser2 vs sax vs xml2js: Parsing Strategies Compared
When working with structured text like HTML or XML in Node.js, choosing the right parser affects performance, memory usage, and code complexity. cheerio, htmlparser2, sax, and xml2js each solve this problem differently. Let's compare how they handle common engineering tasks.
𧩠Interaction Model: DOM vs Events vs Objects
cheerio loads the entire document into a DOM-like structure.
- You interact with it using selectors similar to jQuery.
- Best for random access and manipulation of nodes.
// cheerio: DOM manipulation
const cheerio = require('cheerio');
const $ = cheerio.load('<ul><li class="item">Hello</li></ul>');
const text = $('.item').text();
console.log(text); // "Hello"
htmlparser2 emits events as it reads the stream.
- You define callbacks for tags, text, and errors.
- Best for custom logic without building a full tree.
// htmlparser2: Event-based parsing
const { Parser } = require('htmlparser2');
const parser = new Parser({
onopentag: (name, attribs) => console.log(`Start: ${name}`),
ontext: (text) => console.log(`Text: ${text}`)
});
parser.write('<li class="item">Hello</li>');
parser.end();
sax is strictly event-based for XML.
- It enforces XML rules and emits events for opens, closes, and text.
- Best for strict XML processing where structure matters.
// sax: Strict XML events
const sax = require('sax');
const parser = sax.createStream(true);
parser.onopentag = (node) => console.log(`Tag: ${node.name}`);
parser.ontext = (text) => console.log(`Text: ${text}`);
parser.write('<item>Hello</item>').end();
xml2js converts XML directly into JavaScript objects.
- You get a nested object structure after parsing completes.
- Best for data extraction without manual traversal.
// xml2js: Object conversion
const xml2js = require('xml2js');
const parser = new xml2js.Parser();
parser.parseStringPromise('<item>Hello</item>').then((result) => {
console.log(result.item);
});
π¦ Memory Usage: Buffering vs Streaming
Memory management is critical when processing large files.
cheeriobuffers the whole document.- Loads everything into memory before you can query.
- Simple to use but risky for very large files.
// cheerio: Buffers entire HTML
const $ = cheerio.load(largeHtmlString);
// Entire DOM is in memory now
htmlparser2supports streaming.- Processes chunks as they arrive.
- Keeps memory footprint low regardless of file size.
// htmlparser2: Stream processing
const parser = new Parser({ onopentag: ... });
stream.pipe(parser); // Process as data flows
saxis inherently streaming.- Designed for large XML feeds.
- No full document tree is built.
// sax: Stream processing
const parser = sax.createStream(true);
fs.createReadStream('large.xml').pipe(parser);
xml2jsbuffers the result.- Builds a complete JavaScript object in memory.
- Convenient but can crash on massive inputs.
// xml2js: Buffers entire object
const result = await parser.parseStringPromise(largeXmlString);
// Entire object tree is in memory now
π‘οΈ HTML Tolerance vs XML Strictness
How the parser handles malformed input varies significantly.
cheerioandhtmlparser2are tolerant.- They fix unclosed tags and handle broken HTML gracefully.
- Ideal for scraping real-world websites.
// cheerio: Handles broken HTML
const $ = cheerio.load('<div><p>Unclosed');
console.log($.html()); // Outputs corrected HTML
saxandxml2jsare strict.- They expect well-formed XML.
- Will throw errors on missing closing tags or invalid characters.
// sax: Fails on broken XML
parser.onerror = (err) => console.error('Strict error:', err);
parser.write('<item>Unclosed'); // Triggers error
π Data Extraction Patterns
Extracting specific values looks different across these tools.
cheeriouses CSS selectors.- Concise and readable for front-end developers.
// cheerio: CSS selector
const price = $('.product-price').text();
htmlparser2requires state tracking.- You must track when you are inside a target tag.
// htmlparser2: Manual state tracking
let inPrice = false;
const parser = new Parser({
onopentag: (name) => { if (name === 'price') inPrice = true; },
ontext: (text) => { if (inPrice) console.log(text); },
onclosetag: (name) => { if (name === 'price') inPrice = false; }
});
saxsimilar tohtmlparser2but for XML.- Requires manual event handling for extraction.
// sax: Manual event handling
let currentTag = '';
parser.onopentag = (node) => { currentTag = node.name; };
parser.ontext = (text) => { if (currentTag === 'price') console.log(text); };
xml2jsuses object paths.- Direct access via property names.
// xml2js: Object property access
const price = result.product.price[0];
π Summary: Key Differences
| Feature | cheerio | htmlparser2 | sax | xml2js |
|---|---|---|---|---|
| Input | HTML / XML | HTML / XML | XML Only | XML Only |
| Model | DOM (jQuery-like) | Events (Streaming) | Events (Streaming) | Object Conversion |
| Memory | High (Buffers All) | Low (Streaming) | Low (Streaming) | High (Buffers All) |
| Strictness | Tolerant | Tolerant | Strict | Strict |
| Best For | Scraping | Custom Processors | Legacy XML | Config/Data Load |
π€ Similarities: Shared Ground
Despite their differences, these libraries share some core traits.
1. βοΈ Node.js Native Focus
- All are designed primarily for server-side JavaScript.
- No dependency on browser DOM APIs.
// All run in Node.js environment
const http = require('http');
// Use any of the parsers here
2. π Event or Callback Based
- Even
cheerioandxml2jsrely on underlying event systems. - Asynchronous patterns are common across the board.
// xml2js uses promises/callbacks
await parser.parseStringPromise(xml);
// htmlparser2 uses events
parser.on('text', handler);
3. π Text Processing
- All handle string encoding and decoding.
- Support for UTF-8 and standard web encodings.
// All handle standard text inputs
const html = '<div>Text</div>';
π‘ The Big Picture
cheerio is like a Swiss Army knife πͺ for HTML β perfect for scraping and quick manipulation where developer speed matters most. Use it for web scrapers, static site generators, or testing HTML output.
htmlparser2 is like a raw engine ποΈ β fast and flexible but requires more code. Use it when building tools that process huge HTML files or need custom logic without DOM overhead.
sax is like a precision gauge π β strict and reliable for XML. Use it for legacy XML feeds or when compliance is non-negotiable.
xml2js is like a translator π£οΈ β converts XML to usable data structures instantly. Use it for configuration files, SOAP APIs, or data imports where you need objects, not DOM nodes.
Final Thought: For most modern web scraping tasks, cheerio offers the best balance of power and ease. For heavy data processing or strict XML needs, lean on htmlparser2 or xml2js respectively. Avoid loading massive files into memory with cheerio or xml2js if performance is critical.
How to Choose: cheerio vs htmlparser2 vs sax vs xml2js
- cheerio:
Choose
cheeriowhen you need to scrape websites or manipulate HTML structures using familiar jQuery selectors. It is the best fit for tasks requiring DOM traversal, modification, or extraction where ease of use matters more than raw streaming performance. - htmlparser2:
Choose
htmlparser2when you need high-performance parsing of large HTML or XML files without loading the entire document into memory. It is suitable for building custom tools, linters, or processors where you need direct control over parsing events. - sax:
Choose
saxwhen you require strict XML compliance and need a low-level streaming interface for legacy systems or specific XML standards. It is best for scenarios where validation and strict adherence to XML specs are critical. - xml2js:
Choose
xml2jswhen your goal is to convert XML data directly into JavaScript objects for easy access. It is ideal for handling configuration files, SOAP responses, or any scenario where you need structured data rather than DOM manipulation.
Popular Comparisons
README for cheerio
cheerio
The fast, flexible, and elegant library for parsing and manipulating HTML and XML.
import * as cheerio from 'cheerio';
const $ = cheerio.load('<h2 class="title">Hello world</h2>');
$('h2.title').text('Hello there!');
$('h2').addClass('welcome');
$.html();
//=> <html><head></head><body><h2 class="title welcome">Hello there!</h2></body></html>
Installation
Install Cheerio using a package manager like npm, yarn, or bun.
npm install cheerio
# or
bun add cheerio
Features
β€ Proven syntax: Cheerio implements a subset of core jQuery. Cheerio removes all the DOM inconsistencies and browser cruft from the jQuery library, revealing its truly gorgeous API.
Ο Blazingly fast: Cheerio works with a very simple, consistent DOM model. As a result parsing, manipulating, and rendering are incredibly efficient.
β Incredibly flexible: Cheerio wraps around parse5 for parsing HTML and can optionally use the forgiving htmlparser2. Cheerio can parse nearly any HTML or XML document. Cheerio works in both browser and server environments.
API
Loading
First you need to load in the HTML. This step in jQuery is implicit, since jQuery operates on the one, baked-in DOM. With Cheerio, we need to pass in the HTML document.
// ESM or TypeScript:
import * as cheerio from 'cheerio';
// In other environments:
const cheerio = require('cheerio');
const $ = cheerio.load('<ul id="fruits">...</ul>');
$.html();
//=> <html><head></head><body><ul id="fruits">...</ul></body></html>
Selectors
Once you've loaded the HTML, you can use jQuery-style selectors to find elements within the document.
$( selector, [context], [root] )
selector searches within the context scope which searches within the root
scope. selector and context can be a string expression, DOM Element, array
of DOM elements, or cheerio object. root, if provided, is typically the HTML
document string.
This selector method is the starting point for traversing and manipulating the document. Like in jQuery, it's the primary method for selecting elements in the document.
$('.apple', '#fruits').text();
//=> Apple
$('ul .pear').attr('class');
//=> pear
$('li[class=orange]').html();
//=> Orange
Rendering
When you're ready to render the document, you can call the html method on the
"root" selection:
$.root().html();
//=> <html>
// <head></head>
// <body>
// <ul id="fruits">
// <li class="apple">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
// </body>
// </html>
If you want to render the
outerHTML
of a selection, you can use the outerHTML prop:
$('.pear').prop('outerHTML');
//=> <li class="pear">Pear</li>
You may also render the text content of a Cheerio object using the text
method:
const $ = cheerio.load('This is <em>content</em>.');
$('body').text();
//=> This is content.
The "DOM Node" object
Cheerio collections are made up of objects that bear some resemblance to browser-based DOM nodes. You can expect them to define the following properties:
tagNameparentNodepreviousSiblingnextSiblingnodeValuefirstChildchildNodeslastChild
Screencasts
This video tutorial is a follow-up to Nettut's "How to Scrape Web Pages with Node.js and jQuery", using cheerio instead of JSDOM + jQuery. This video shows how easy it is to use cheerio and how much faster cheerio is than JSDOM + jQuery.
Cheerio in the real world
Are you using cheerio in production? Add it to the wiki!
Sponsors
Does your company use Cheerio in production? Please consider sponsoring this project! Your help will allow maintainers to dedicate more time and resources to its development and support.
Headlining Sponsors
Other Sponsors
Backers
Become a backer to show your support for Cheerio and help us maintain and improve this open source project.
License
MIT