Skip to content

Cheerio npm for Static HTML Scraping: Selectors, Iteration, and CSV Export

Cheerio is a Node.js library that builds a virtual DOM from an HTML string and lets you query it with jQuery-style selectors. It does not run JavaScript or apply CSS, which makes it fast and well suited to server-side parsing of static markup. This guide walks through setup, loading HTML, selecting and iterating nodes, and exporting a scraped table to CSV. It also explains when a JavaScript-capable tool such as jsdom is the better choice.

What Cheerio does and does not do

Cheerio parses an HTML string into an in-memory tree. You then use selection expressions to find nodes and read their text or attributes. Because no browser rendering happens, Cheerio is quick and can run in a serverless function or any Node.js process.

The important limitation is that Cheerio does not execute page scripts or apply styles. If the data you need is inserted by client-side JavaScript after the initial HTML loads, Cheerio will not see it. In that case, a tool that can run JavaScript, such as jsdom, is more appropriate. For static HTML, including server-rendered tables and saved page copies, Cheerio is usually sufficient.

Project setup

You need Node.js installed. The Long-Term Support (LTS) release is the recommended baseline. Create a project directory and initialize it with npm, then add the runtime and development dependencies used in this walkthrough. The exact commands are preserved in the supplied setup modules.

The runtime dependencies are cheerio for parsing and axios for downloading page content. The development dependencies are typescript, esbuild, and esbuild-runner so the TypeScript source can be executed directly. A package.json script named scrape runs the entry file through esr.

Loading an HTML string

Cheerio's load method accepts an HTML string and returns a query function. Cheerio does not fetch the string for you. You can pass a hard-coded constant, read a local HTML file, or supply content downloaded over HTTP.

For tests, saving a copy of the target page locally is a practical way to avoid connectivity problems. The example below loads a small string containing two h2 elements, one of which has the class primary.

Selecting nodes

Selection uses jQuery-style expressions. To read the first matching header, select h2.primary and call text on the result. Running the scrape script should print First Header, which confirms that the string was parsed and the class-qualified selector matched.

A selector that returns nothing is usually a sign that the markup differs from what you expected. Check the saved HTML rather than assuming the page is broken.

Iterating over multiple nodes

When a selector matches several elements, use each. The callback receives the current index and a reference to the element. Pass that reference back into the Cheerio query function to get a wrapped element whose text method you can call.

With the sample string, iterating over all h2 nodes prints First Header followed by Second Header.

Worked example: a population table

The walkthrough scrapes a Wikipedia table of countries and dependencies by population and writes the rows to a CSV file. The table is a dated reference; population figures and row counts change over time, so check the current page before relying on any value.

The workflow has five stages: request the page, load the response into Cheerio, locate the table and its rows, extract header keys and cell values, and save the result. The code modules preserve each stage exactly.

Finding the right table nodes

Open the target page in a browser, inspect the table, and test selectors in the developer tools. For this page, table.wikitable selects the table, and table.wikitable tr selects its rows. The row count is a little under 250 at the time of the walkthrough.

A subtlety matters here. The browser shows a thead element, but the downloaded HTML does not contain one; the browser creates it from the first body row. A selector such as table.wikitable > thead > tr therefore will not work in Cheerio. Select rows through the table and treat the first row as the header row.

Extracting header keys and cell values

For the first row, collect the text of each th element, trim it, and store it as a key. Return from that iteration so the header row is not added as a data record. For every later row, read each td or th cell, trim its text, pair it with the key at the same index, and push the resulting object into the results array.

When the script runs, it prints the column names and the number of results. The captured run showed keys for Rank, Country or dependent territory, Region, Population, % of world, Date, Source, and Notes, and reported 242 results. Those values describe that run, not the current page.

Saving the rows as CSV

The json2csv package converts the array of objects into CSV text, and the promise-based fs module writes it to output.csv with UTF-8 encoding. Install json2csv, import it alongside fs/promises, define an async save function, and pass the scraper results to it.

After the script finishes, open output.csv in a spreadsheet or data tool. The file contains the parsed table rows with the header keys as column names.

Decision checklist before you scrape

Use this checklist to avoid the most common mismatch between the tool and the page.

  • Is the target data present in the HTML that the server returns? If yes, Cheerio is a good fit.
  • Is the data inserted only after client-side JavaScript runs? If yes, use a JavaScript-capable tool such as jsdom or a browser-based scraper.
  • Have you saved a copy of the HTML and tested selectors against that copy? This separates selector problems from network problems.
  • Does the page structure include elements that the browser creates dynamically, such as a thead? Select through stable ancestors instead.
  • Have you checked the site's terms and any applicable rules before collecting data?
  • Will the output be reviewed for stale values before it is used for decisions?

Field and control map for the example

The table below summarizes how each part of the example maps to a concrete input or output. It is a reader aid, not a replacement for the preserved code modules.

StageInput or controlOutput
RequestTarget URL passed to axios.getHTML response data
ParseHTML string passed to cheerio.loadQuery function
Locate tableSelector table.wikitableTable node
Locate rowsSelector tr within the tableRow nodes
Header keysText of th cells in the first rowKey array
Data valuesText of td or th cells in later rowsObjects with keyed values
Exportjson2csv parser and fs writeFileoutput.csv

Frequently asked questions

Can Cheerio scrape content that only appears after JavaScript runs?

No. Cheerio parses the HTML string it is given and does not execute page scripts. If the data is inserted by client-side JavaScript, use a tool that can run JavaScript, such as jsdom, or a browser-based scraper.

Why does a thead selector fail in Cheerio when the browser shows a thead?

The browser can create a thead from the first body row, so the element may not exist in the downloaded HTML. Select rows through the table and treat the first row as the header row instead.

Does Cheerio download web pages?

No. Cheerio only parses an HTML string. You supply the string from a constant, a local file, or an HTTP request made with a library such as axios.

What format does the example produce?

The example converts the scraped rows to CSV with json2csv and writes them to output.csv using the promise-based fs module.

"scripts": {
  "scrape": "esr ./src/index.ts"
}