Skip to content

Cheerio in JavaScript: What It Does and When to Use It

Cheerio gives JavaScript and Node.js developers a jQuery-like way to read HTML and XML.

OUTPUT FORMATSHTMLJSONMarkdown

It is fast because it only parses markup: it does not run scripts inside the document and does not fetch external resources. That makes it a strong fit for static pages and a poor fit for pages whose content appears only after client-side JavaScript or background XHR calls.

What Cheerio is

Cheerio implements the core of jQuery's API for traversing and selecting nodes. The same familiar selector style works in the browser and on the server, so a parsing routine can move between environments without a rewrite. It accepts HTML and XML input and returns a queryable structure you can walk with selectors.

The important boundary is what Cheerio does not do. It does not execute JavaScript found in the page, and it does not load external resources such as images or stylesheets. Those omissions are the reason it is much faster than full browser automation tools like Puppeteer and Selenium, which must launch and drive a real browser.

When Cheerio is the right tool

Use Cheerio when the markup you need is already present in the HTML or XML you have fetched. Typical jobs include pulling a page title, collecting links, reading table rows, selecting elements by class or attribute, and walking sibling nodes. Because the parser is lightweight, it scales well across many documents.

A quick decision checklist:

  • Is the target data in the raw HTML or XML? If yes, Cheerio is a candidate.
  • Does the page need JavaScript to render the data? If yes, a browser-driven tool is the better fit.
  • Does the data arrive through background XHR requests? If yes, Cheerio alone will not see it.
  • Do you need to load external resources? If yes, Cheerio will not do that.

If every answer points to static markup, Cheerio is usually the leaner choice.

When Cheerio is not the right tool

Cheerio is not designed for pages that build their content in the browser or fetch data after the initial document loads. If a project requires executing JavaScript on the page or issuing background XHR requests, Cheerio cannot produce the rendered result on its own. In those cases, a full browser automation tool such as Puppeteer or Selenium is the appropriate choice.

A useful failure distinction: an empty selector result from Cheerio can mean either (a) your selector is wrong, or (b) the content was never in the fetched HTML to begin with. Check the raw response first. If the data is absent there, no selector fix will help; you need a tool that executes scripts or captures XHR responses.

A small worked example

Consider a static HTML fragment that contains a heading and a link. Cheerio can select the heading text and read the link's href attribute directly from the markup. It can also select elements by class or attribute and walk to sibling nodes.

Now imagine the same page loads its product list through a background XHR call after the initial HTML arrives. Cheerio will see the empty container but not the products, because it does not execute the script that triggers the request. The fix is not a better selector; it is a tool that runs the page's JavaScript or captures the XHR response. This example captures the core trade-off: Cheerio is fast and simple for static markup, and intentionally limited for dynamic pages.

Frequently asked questions

Does Cheerio execute JavaScript on the page?

No. Cheerio parses HTML and XML but does not execute scripts inside the document. If the data you need is rendered by JavaScript, Cheerio will not see it unless that data is already present in the fetched markup.

Why is Cheerio faster than Puppeteer or Selenium?

Cheerio only parses markup. It does not launch a browser, run page scripts, or load external resources. Puppeteer and Selenium must drive a real browser, which is heavier. That speed advantage disappears for pages that need script execution, where Cheerio cannot produce the rendered result.

Can Cheerio capture background XHR requests?

No. Cheerio does not issue or capture XHR requests. If a page loads its data through background XHR, you need a tool that executes the page's JavaScript or intercepts network responses.

Why does my Cheerio selector return nothing?

Check the raw HTML first. If the target content is absent from the fetched markup, the selector is not the problem; the page likely renders that content with JavaScript or XHR. If the content is present, review your selector syntax and traversal path.