Skip to content

Cheerio for Web Scraping: A Practical Selector and Extraction Guide

Cheerio is a fast, server-side HTML parsing library for JavaScript.

OUTPUT FORMATSHTMLJSONMarkdown

It gives you a jQuery-like API to walk a document, select nodes and pull out text or attributes, without launching a browser. That makes it a strong first choice when the data you need is already in the HTML your request receives. This guide explains what Cheerio does, how to target the elements you want, and where its limits mean you should reach for a headless browser instead.

What Cheerio is and where it fits

Cheerio parses an HTML string into a queryable tree. You load markup, then use CSS-style selectors to find elements and read their contents. It runs in Node.js and does not render pages, execute scripts or manage a browser session. Because of that, it is lightweight and quick on static HTML. The trade-off is that anything injected by client-side JavaScript after load will not be present in the string you hand to Cheerio. If your target data appears only after scripts run, you need a browser-based tool. If it is in the initial response, Cheerio usually gets you there with less overhead.

Cheerio vs Puppeteer: which to pick

The decision comes down to how the page delivers its content. Use this checklist before writing a scraper:

  • Is the data present in the raw HTML response? If yes, Cheerio is a good fit.
  • Does the page require JavaScript to build the content, log in, or interact with controls? If yes, use a headless browser such as Puppeteer.
  • Do you need screenshots, clicks, scrolling or waiting for network activity? Those are browser tasks, not parsing tasks.
  • Do you only need to read and transform HTML you already have? Cheerio handles that without the cost of a browser.

A common pattern is to fetch or render a page with a browser tool, then pass the resulting HTML to Cheerio for structured extraction. The two are complementary rather than strictly competing.

Selector and extraction map

The table below maps a scraping goal to the Cheerio approach and the kind of output you should expect. Treat it as a quick reference when you know what you want but not which method to reach for.

Finding the right elements

Cheerio supports CSS selectors, so you can target elements by tag, class, attribute or combinations of them. To find elements by class, use a class selector such as a leading dot followed by the class name. To find elements by attribute, use an attribute selector in square brackets. To match several tags at once, combine tag selectors. When an element has no distinctive attribute, you can still locate it by its position, its parent, or its surrounding structure.

XPath is a separate query language. Cheerio's core selection is CSS-based, so if you are coming from an XPath workflow, plan to translate your expressions into CSS selectors or use a dedicated XPath library alongside Cheerio. Sibling traversal is handled through Cheerio's tree navigation methods, which let you move from one node to adjacent nodes when the data you want sits next to a known anchor element.

A small worked example

Suppose the HTML you are parsing contains a set of question headings, each followed by a short answer. You want a list of question-and-answer pairs. The steps are:

  1. Load the HTML string into Cheerio.
  2. Select the heading elements that mark each question.
  3. For each heading, read its text as the question.
  4. Move to the next sibling node to capture the answer text.
  5. Push each pair into an array.

If step 4 returns nothing, the answer is probably not a direct sibling. Check whether it is wrapped in a container, and adjust the traversal to go up to the shared parent and then down to the answer. This is the most common reason a sibling-based extraction comes back empty.

Why an extraction returns nothing

An empty result usually has one of three causes, and they need different fixes:

  • The selector matches nothing. The class, attribute or tag name is wrong, or the element is nested differently than expected. Inspect the actual markup and confirm the selector against it.
  • The element exists but the attribute you read is absent. Reading href on a non-anchor, or a data attribute that is not set, yields an empty value. Check that the attribute is present on the matched nodes.
  • The content is added by JavaScript after the initial response. Cheerio sees only the HTML string it was given. If the data is not in that string, no selector will find it; you need a rendering step first.

Separating these cases early saves time, because only the third requires changing your tooling rather than your selector.

Cheerio selector and extraction reference
GoalApproachExpected output
Find elements by classClass selector (leading dot plus class name)Matched elements
Find elements by attributeAttribute selector in square bracketsMatched elements
Find elements by multiple tagsCombined tag selectorsMatched elements
Find elements without specific attributesPosition, parent or structural selectorMatched elements
Find sibling nodesTree navigation from a known anchor nodeAdjacent nodes
Scrape a tableSelect table, iterate rows, iterate cellsStructured records
Get the page titleSelect the title element and read its textTitle string
Get linksSelect anchors and read the href attributeList of URLs
Select values between two nodesAnchor on start and end nodes, collect in betweenNode range

This reference describes general Cheerio capabilities and is not tied to a specific version or site.

Frequently asked questions

What is Cheerio in JavaScript?

Cheerio is a server-side HTML parsing library for JavaScript. It loads an HTML string and lets you query it with CSS-style selectors, similar to how jQuery works in the browser. It does not render pages or run scripts, so it works on the markup you supply.

Is Cheerio faster than Puppeteer?

For parsing static HTML, Cheerio avoids the cost of launching and driving a browser, so it is generally lighter and quicker. Puppeteer is needed when content depends on JavaScript, interaction or rendering. The right comparison depends on whether your target data is in the initial HTML.

Can I use XPath selectors in Cheerio?

Cheerio's core selection is CSS-based. If your workflow depends on XPath expressions, translate them into CSS selectors or pair Cheerio with a dedicated XPath library.

How do I get links in Cheerio?

Select the anchor elements, then read the href attribute on each matched node. Reading the element's text gives you the link label, not the destination.

How do I scrape tables with Cheerio?

Select the table element, iterate its rows, and within each row iterate its cells. Collect the text from each cell into a record, and read the header row first if you want named columns.