# Technical Documentation: cheeriojs/cheerio > ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/cheeriojs/cheerio) ### Overview (`Readme.md`)

cheerio

The fast, flexible, and elegant library for parsing and manipulating HTML and XML.

[中文文档 (Chinese Readme)](https://github.com/cheeriojs/cheerio/wiki/Chinese-README) ```js import * as cheerio from 'cheerio'; const $ = cheerio.load('

Hello world

'); $('h2.title').text('Hello there!'); $('h2').addClass('welcome'); $.html(); //=>

Hello there!

``` ## Installation Install Cheerio using a package manager like npm, yarn, bun, or Deno. ```bash npm install cheerio # or bun add cheerio # or deno install 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](https://github.com/inikulin/parse5) for parsing HTML and can optionally use the forgiving [htmlparser2](https://github.com/fb55/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. ```js // ESM or TypeScript: import * as cheerio from 'cheerio'; // In other environments: const cheerio = require('cheerio'); const $ = cheerio.load('

...'); $.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. ```js $('.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: ```js $.root().html(); //=> // // //

Apple
Orange
Pear

// // ``` If you want to render the [`outerHTML`](https://developer.mozilla.org/en-US/docs/Web/API/Element/outerHTML) of a selection, you can use the `outerHTML` prop: ```js $('.pear').prop('outerHTML'); //=>

Pear

``` You may also render the text content of a Cheerio object using the `text` method: ```js const $ = cheerio.load('This is content.'); $('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](https://developer.mozilla.org/en-US/docs/Web/API/Node). You can expect them to define the following properties: - `tagName` - `parentNode` - `previousSibling` - `nextSibling` - `nodeValue` - `firstChild` - `childNodes` - `lastChild` ## Screencasts [https://vimeo.com/31950192](https://vimeo.com/31950192) > 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](https://github.com/cheeriojs/cheerio/wiki/Cheerio-in-Production)! ## Sponsors Does your company use Cheerio in production? Please consider [sponsoring this project](https://github.com/cheeriojs/cheerio?sponsor=1)! Your help will allow maintainers to dedicate more time and resources to its development and support. **Headlining Sponsors**

**Other Sponsors**

## Backers [Become a backer](https://github.com/cheeriojs/cheerio?sponsor=1) to show your support for Cheerio and help us maintain and improve this open source project.

## License MIT --- ### Overview (`website/README.md`) # Website This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator. ### Installation ``` $ yarn ``` ### Local Development ``` $ yarn start ``` This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. ### Build ``` $ yarn build ``` This command generates static content into the `build` directory and can be served using any static contents hosting service. --- ### Website Src Content Docs Intro (`website/src/content/docs/intro.md`) --- sidebar_position: 1 sidebar_label: Introduction --- # Welcome to Cheerio! Cheerio parses HTML and XML, and gives you a jQuery-like API for traversing and manipulating the result. This page takes you from installation to your first scrape in about five minutes. :::note[Cheerio is not a web browser] Cheerio parses markup and provides an API for working with the resulting data structure. It does not interpret that markup the way a browser does: there is no visual rendering, no CSS, no loading of external resources, and no JavaScript execution. That is what makes Cheerio **much faster** than browser-based tools — but it also means content that a single-page app renders on the client won't be there. If you need any of that, reach for browser automation such as [Puppeteer](https://github.com/puppeteer/puppeteer) or [Playwright](https://github.com/microsoft/playwright), or a DOM emulation project like [jsdom](https://github.com/jsdom/jsdom). ::: ## Installation Cheerio runs on Node.js 22.19 or later. Once you have [Node.js](https://nodejs.org/en/download/) installed, add Cheerio to your project: ```bash npm install cheerio ``` Then import it: ```js import * as cheerio from 'cheerio'; ``` If you prefer CommonJS, `require` works too: ```js const cheerio = require('cheerio'); ``` ## Loading a document Every Cheerio session starts by loading a document. The simplest way is `load`, which takes a string of markup: ```js const $ = cheerio.load('

Hello world

'); ``` `load` returns a `$` function that you use to query the document, just like jQuery's `$`. Cheerio can also load documents from buffers, streams, and URLs — see [loading documents](/docs/basics/loading) for the full list. ## Selecting elements Call `$` with a [CSS selector](/docs/basics/selecting) to find elements. Here we select the `

` with the class `title` and read its text: ```js $('h2.title').text(); // "Hello world" ``` ## Traversing the DOM `$` returns a `Cheerio` object — a list of matched elements with methods for moving around the document. For example, `find` searches within the current selection: ```js const $ = cheerio.load(`

Hello world

Nice to meet you

`); $('.post').find('.subtitle').text(); // "Nice to meet you" ``` There are methods for moving up, down, and sideways through the tree, plus a range of filters. See [traversing the DOM](/docs/basics/traversing). ## Manipulating elements The same methods that read values also write them. Passing an argument to `text()` replaces the text content, and methods like `after()` insert new markup: ```js $('h2.title').text('Hello there!'); $('h2').after('

How are you?

'); ``` Call `$.html()` at any point to serialize the document back to a string. See [manipulating elements](/docs/basics/manipulation) for the full set of methods. --- ### Website Src Content Docs Advanced Configuring Cheerio (`website/src/content/docs/advanced/configuring-cheerio.md`) --- sidebar_position: 2 description: Configure Cheerio to work with different documents. --- # Configuring Cheerio Cheerio ships with two parsers and picks between them based on the options you pass to `.load()`: - [`parse5`](https://parse5.js.org/) — the default for HTML. It rigorously conforms to the HTML standard, so it produces the same tree a browser would. - [`htmlparser2`](https://github.com/fb55/htmlparser2) — the default for XML. It is faster, uses less memory, and is more forgiving of malformed markup. This guide covers how to configure each of them. ## Parsing HTML with parse5 `parse5` is used automatically for HTML. To change how it parses, pass an options object as the second argument to `.load()`: ```js import * as cheerio from 'cheerio'; // With scripting disabled, the contents of ', { scriptingEnabled: false, }); ``` For a full list of options and their effects, have a look at [the API documentation](/docs/api/interfaces/CheerioOptions). ### Fragment Mode By default, `parse5` treats its input as a complete document and wraps the content in ``, ``, and `` elements — exactly as a browser would: ```js const $ = cheerio.load('

Apple

Banana

'); $.html(); // => '

Apple

Banana

' ``` Pass `false` as the third argument to parse the input as a fragment instead, without adding the surrounding document structure: ```js const $ = cheerio.load('

Apple

Banana

', {}, false); $.html(); // => '

Apple

Banana

' ``` This is usually what you want when the input is a snippet of a larger page — a table row or a list item, say — rather than a page of its own. ## Parsing XML with htmlparser2 To parse a document as XML, set the `xml` option. Cheerio then uses `htmlparser2`, which — unlike `parse5` — will not add HTML-specific structure or apply HTML parsing rules: ```js const $ = cheerio.load('

...', { xml: true, }); ``` If you need to customize the parsing options for XML input, you may pass an object as the `xml` option to `.load()`, with the options you want to change: ```js const $ = cheerio.load('

...', { xml: { withStartIndices: true, }, }); ``` When `xml` is set, the default options are: ```js { xmlMode: true, // Enable htmlparser2's XML mode. decodeEntities: true, // Decode HTML entities. withStartIndices: false, // Add a `startIndex` property to nodes. withEndIndices: false, // Add an `endIndex` property to nodes. } ``` These options are passed straight through to `htmlparser2`, so anything valid there is valid here. For a full list, see [the API documentation](/docs/api/interfaces/HTMLParser2Options). ### Using `htmlparser2` for HTML You may want `htmlparser2` to parse HTML too — if you are upgrading from a pre-1.0 release of Cheerio (which used it by default), if the browser parsing rules `parse5` applies get in your way (`htmlparser2` is more forgiving[^1]), or if you are in a performance-critical situation (it is faster and the resulting DOM uses less memory). [^1]: "More forgiving" means `htmlparser2` has error-correcting mechanisms that aren't always a match for the standards observed by web browsers. This behavior may be useful when parsing non-HTML content. To do that, disable `xmlMode` inside the `xml` option: ```js const $ = cheerio.load('

...', { xml: { // Disable `xmlMode` to parse HTML with htmlparser2. xmlMode: false, }, }); ``` :::tip[The slim export] If you never need `parse5`, import Cheerio's _slim_ export instead. It always uses `htmlparser2` and leaves `parse5` out of the bundle entirely — worth doing in browser environments: ```js import * as cheerio from 'cheerio/slim'; ``` ::: `.load()` also accepts an already-parsed, `htmlparser2`-compatible document as its first argument: ```js import * as htmlparser2 from 'htmlparser2'; const dom = htmlparser2.parseDocument('

...', { xmlMode: true, }); const $ = cheerio.load(dom); ``` :::warning This route still uses `parse5`'s serializer, so `$.html()` returns HTML rather than XML and ignores the options you passed to `htmlparser2`. Disabling `xmlMode` as shown above is the recommended approach. ::: --- ### Website Src Content Docs Advanced Extending Cheerio (`website/src/content/docs/advanced/extending-cheerio.md`) --- sidebar_position: 999 description: Create custom pseudo-classes and plugins. --- # Extending Cheerio Cheerio has two extension points: you can teach its selector engine new pseudo-classes, and you can add your own methods to the `Cheerio` prototype. ## Adding Custom CSS Pseudo-Classes The `pseudos` option maps pseudo-class names to either a string or a function: - A **string** is a selector the element must match to be selected. - A **function** is called with the element as its first argument and the pseudo-class's parameter as its second. Return `true` to select the element. ```js const $ = cheerio.load('

', { pseudos: { // `:foo` is an alias for `div.foo` foo: 'div.foo', // `:bar(val)` is equivalent to `[data-bar=val s]` bar: (el, val) => el.attribs['data-bar'] === val, }, }); $(':foo').length; // 1 $('div:bar(boo)').length; // 1 $('div:bar(baz)').length; // 0 ``` ## Writing Plugins for Cheerio Every loaded document has its own `Cheerio` prototype, reachable as `$.prototype` or its alias `$.fn`. Adding a method there makes it available on every selection from that document — and only that one, so plugins don't leak between documents. ```js const $ = cheerio.load('Hello, world!'); $.fn.logHtml = function () { console.log(this.html()); }; $('body').logHtml(); // logs "Hello, world!" to the console ``` Inside the method, `this` is the current selection, so the full Cheerio API is available to you. If you're using TypeScript, declare the method so the compiler knows about it: ```ts declare module 'cheerio' { interface Cheerio { logHtml(this: Cheerio): void; } } ``` --- ### Website Src Content Docs Advanced Security (`website/src/content/docs/advanced/security.md`) --- sidebar_position: 3 description: Handling untrusted markup safely. --- # Security Cheerio is usually pointed at pages someone else controls, so it is worth being explicit about what it does and does not protect you from. Cheerio parses markup, lets you query and change the resulting tree, and serializes it back to markup. It **never executes scripts, evaluates expressions, or touches the network** — the one exception being [`fromURL`](/docs/basics/loading#fromurl), which makes the request you asked for. ## Cheerio is not a sanitizer This is the big one. Cheerio's output is *markup*, not *safe* markup. If you load a page containing ` `); console.log(JSON.stringify($('div').text())); console.log(JSON.stringify($('div').prop('innerText'))); ``` ## `text()` is full of whitespace Cheerio preserves the document's whitespace exactly, including the newlines and indentation between tags. Browsers collapse that when rendering; Cheerio does not. Trim it yourself: ```js live const $ = cheerio.load(`

Apple

`); console.log(JSON.stringify($('li').text())); console.log(JSON.stringify($('li').text().trim())); ``` Note that `.prop('innerText')` does *not* help here — it skips `