Cheerio

Cheerio is a free, open-source JavaScript library for parsing HTML and XML strings and manipulating the resulting document with a jQuery-like syntax, widely used for server-side web scraping and HTML transformation. It runs in Node.js and in browsers, accepts a document string as input, and outputs serialized HTML or plain text via its .html() and .text() methods. The project is maintained by the cheeriojs organization on GitHub and has over 30,000 stars.

What is Cheerio?

Cheerio parses an HTML or XML document into a lightweight DOM tree and exposes a jQuery-style API for selecting elements, traversing the tree, and mutating content. It takes a document string (for example, fetched HTML from a URL) and returns a queryable object that behaves like jQuery's $. The library is built on the parse5 HTML parser by default and can optionally use the more forgiving htmlparser2, and it is packaged as an ESM or CommonJS module.

Key Features

• jQuery syntax subset — Implements a subset of core jQuery methods including selectors, .text(), .attr(), .html(), and .addClass(), so developers familiar with jQuery can start immediately.
• Fast parsing — A simple, consistent DOM model makes parsing, manipulating, and rendering very efficient compared to a full browser DOM.
• Flexible loading — cheerio.load() accepts HTML or XML strings, and selectors can accept a context and root to scope searches.
• Rendering methods — .html() serializes the full document, .text() extracts text content, and .prop('outerHTML') returns a selection's outer HTML.
• Cross-platform — Works in Node.js, Deno, and browsers, and installs via npm, yarn, bun, or Deno.
• Node-like DOM objects — Cheerio collections expose properties such as tagName, parentNode, previousSibling, nextSibling, nodeValue, and childNodes.

Who is it for?

• Web scrapers — Parse fetched HTML and extract data with CSS selectors, without needing a headless browser.
• Unit test writers — Load HTML fixtures, manipulate them, and assert on the resulting markup using a familiar jQuery API.
• Build tool authors — Transform HTML strings in preprocessing pipelines, such as minifiers or static site generators.

What can you do with Cheerio?

• Web scraping: Load an HTML string, select elements with selectors like $('ul .pear'), extract attribute values or text, and serialize the result.
• Data extraction: Parse XML sitemaps or RSS feeds and pull specific fields using jQuery-style traversal methods.
• HTML transformation: Change class names, text content, or element structure in a script before saving or serving the document.

How does Cheerio work?

1. Install it with a package manager such as npm, bun, or Deno. 2. Import it as ESM (import * as cheerio from 'cheerio') or CommonJS (require('cheerio')). 3. Call cheerio.load(html) to get a $ object. 4. Use selectors and manipulation methods on the object. 5. Render the final HTML with $.html().

Pros and cons

• Pros: Fast, lightweight, familiar jQuery API, works on the server, and available under a permissive MIT license.
• Cons: It parses a string and does not execute a live browser DOM, so it cannot handle JavaScript-driven pages, event handling, or layout — a limitation when a full browser environment is required.

Pricing

Cheerio is free and open-source, released under the MIT License.

Alternatives

• jsdom — A full DOM implementation that simulates a complete browser environment and is often paired with jQuery.
• parse5 — The standards-compliant HTML parser that Cheerio uses by default and is available as a standalone library.
• htmlparser2 — A forgiving HTML/XML parser that Cheerio can optionally use instead of parse5.

FAQ

Is Cheerio free?

Yes, Cheerio is completely free to use and is distributed under the MIT License. You can install it with npm, yarn, bun, or Deno without any licensing fees.

What does Cheerio do?

Cheerio parses an HTML or XML string into a DOM-like structure and provides a jQuery-style API to select elements, read attributes and text, and modify the document. After manipulation, it can render the updated markup as a string.

Can Cheerio parse XML?

The page states that Cheerio can parse nearly any HTML or XML document. It wraps the parse5 parser for HTML and can optionally use htmlparser2, which also supports XML-style documents.

Does Cheerio work in the browser?

Yes, Cheerio works in both browser and server environments. It can be imported with ESM or CommonJS, making it suitable for Node.js scripts and client-side bundlers alike.

How is Cheerio different from jsdom?

Cheerio is a parser and manipulation library that works on a string input and is much faster and lighter than jsdom, which simulates a full browser DOM including event handling and layout. Cheerio is the better choice when you only need to read or transform static HTML.