To scrape a website with Cheerio, download the HTML (Node 18 and later have fetch built in), load it with const $ = cheerio.load(html), and read elements with CSS selectors: $('.price_color').text(). Cheerio parses HTML without running JavaScript, so it is fast, but pages built in the browser need a real browser.
We ran every snippet below on 20 November 2026 with Node.js v22.23.2, cheerio 1.2.0 and undici 7.30.0 on Windows 11, against books.toscrape.com and quotes.toscrape.com, two sandboxes made for scraping practice. The output is copied from those runs.
Set up
npm install cheerio undici
Cheerio 1.x is used as an ES module: import * as cheerio from 'cheerio' in an .mjs file, or with "type": "module" in package.json. undici is only needed for the proxy part; plain requests use the built-in fetch, so axios is optional.
Step 1: download and load the page
import * as cheerio from 'cheerio';
async function getHtml(url, dispatcher) {
const res = await fetch(url, { dispatcher, headers: { 'user-agent': 'my-scraper/1.0 (+https://example.com/bot)' } });
if (!res.ok) throw new Error(`HTTP ${res.status} for ${url}`);
return res.text();
}
const $ = cheerio.load(await getHtml('https://books.toscrape.com/', basic));
console.log('title:', $('title').text().trim());
// title: All products | Books to Scrape - Sandbox
The user agent names the scraper and gives a URL where a site owner can read about it. Check res.ok: fetch does not throw on a 403 or 404, and Cheerio will happily parse an error page. The dispatcher argument is the proxy: in our run, the Residential Basic agent built in step 6. Leave it out and the request leaves from your own connection.
Step 2: select the fields
Cheerio uses the selectors you know from CSS and jQuery. Each book on the page is an article.product_pod:
const books = [];
$('article.product_pod').each((i, el) => {
books.push({
title: $(el).find('h3 a').attr('title'),
price: $(el).find('.price_color').text(),
rating: $(el).find('.star-rating').attr('class').replace('star-rating ', ''),
stock: $(el).find('.availability').text().trim(),
});
});
console.log(books.length, books.slice(0, 2));
20 [
{ title: 'A Light in the Attic', price: '£51.77', rating: 'Three', stock: 'In stock' },
{ title: 'Tipping the Velvet', price: '£53.74', rating: 'One', stock: 'In stock' }
]
| Need | Cheerio call | Our result |
|---|---|---|
| Text of an element | $(el).find('.price_color').text() | £51.77 |
| An attribute | $(el).find('h3 a').attr('title') | A Light in the Attic |
| A list of values | $('.price_color').map((i, el) => $(el).text()).get() | [ '£51.77', '£53.74', '£50.10', ... ] |
| A real array of elements | $('h3 a').toArray() | 20 elements |
Step 3: the shorter way, $.extract()
Cheerio 1.x adds $.extract(), which takes a map of fields to selectors and returns plain objects. The same page in one call:
const data = $.extract({
books: [{
selector: 'article.product_pod',
value: { title: { selector: 'h3 a', value: 'title' }, price: '.price_color', url: { selector: 'h3 a', value: 'href' } },
}],
next: { selector: 'li.next a', value: 'href' },
});
console.log(data.books.length, data.books[0], 'next =', data.next);
20 { title: 'A Light in the Attic', price: '£51.77', url: 'catalogue/a-light-in-the-attic_1000/index.html' } next = catalogue/page-2.html
A field in square brackets returns every match; without brackets, the first. value picks an attribute instead of the text.
Step 4: follow pagination and save a CSV
import { writeFileSync } from 'node:fs';
let url = 'https://books.toscrape.com/catalogue/page-1.html';
const rows = [];
for (let n = 0; n < 3 && url; n++) {
const $p = cheerio.load(await getHtml(url, premium));
$p('article.product_pod').each((i, el) => rows.push({
title: $p(el).find('h3 a').attr('title'),
price: Number($p(el).find('.price_color').text().replace(/[^\d.]/g, '')),
}));
const next = $p('li.next a').attr('href');
url = next ? new URL(next, url).href : null;
console.log('page', n + 1, 'rows so far', rows.length, 'next', url);
}
const csv = ['title,price', ...rows.map((r) => `"${r.title.replace(/"/g, '""')}",${r.price}`)].join('\n');
writeFileSync('books.csv', csv);
page 1 rows so far 20 next https://books.toscrape.com/catalogue/page-2.html
page 2 rows so far 40 next https://books.toscrape.com/catalogue/page-3.html
page 3 rows so far 60 next https://books.toscrape.com/catalogue/page-4.html
new URL(next, url) turns the relative link into a full one, which matters because the site's links change form between the home page and the catalogue pages. The CSV had 61 lines: a header and 60 books. Titles are wrapped in quotes because some contain commas.
Step 5: a detail page and its table
const $d = cheerio.load(await getHtml('https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html', mobile));
const table = Object.fromEntries($d('table.table tr').toArray().map((tr) => [$d(tr).find('th').text(), $d(tr).find('td').text()]));
console.log({ h1: $d('h1').text(), upc: table.UPC, availability: table.Availability, reviews: table['Number of reviews'] });
{ h1: 'A Light in the Attic', upc: 'a897fe39b1053632', availability: 'In stock (22 available)', reviews: '0' }
Step 6: send the requests through a proxy
The built-in fetch takes a dispatcher; undici's ProxyAgent is one. We made one agent per QuanticData network and passed it to getHtml:
import { ProxyAgent } from 'undici';
const agentFor = (host, user, pass) => new ProxyAgent({
uri: `http://${host}`,
token: 'Basic ' + Buffer.from(`${user}:${pass}`).toString('base64'),
});
const basic = agentFor('residentialboson.quanticdata.io:10000', 'USER-type-residential-country-us-session-ch11-lifetime-30', 'PASS');
const premium = agentFor('residentialpremium.quanticdata.io:8080', 'USER-country-us-sid-ch12-ttl-30m', 'PASS');
const mobile = agentFor('mobile.quanticdata.io:8080', 'USER-country-us-type-mobile-sid-ch13-ttl-30m', 'PASS');
| Network | Used for | Exit location (ipinfo.io) | Result |
|---|---|---|---|
| Residential Basic | Home page, steps 1 to 3 | Cambridge, Maryland, US | 20 books |
| Residential Premium | Pagination, step 4 | Dumont, New Jersey, US | 60 books over 3 pages |
| Mobile | Detail page, step 5 | Louisville, Kentucky, US, T-Mobile USA | All table fields |
Each username carries a session ID and a session time; change the ID for a new session. More ways to set a proxy in Node: a proxy in Node.js, Node fetch with a proxy agent and axios with a proxy, if you prefer axios to fetch.
When Cheerio sees nothing: JavaScript pages
quotes.toscrape.com/js/ shows the same quotes as the home page, but writes them with JavaScript after the page loads. Cheerio gets the HTML the server sends:
div.quote found: 0 | static version: 10
Zero matches on a page that clearly shows data in your browser means the data arrives later. Look in the browser's network tab for a JSON request you can call directly (see reading and parsing JSON in JavaScript), or render the page with a browser, as in Playwright for scraping, and pass await page.content() to cheerio.load().
Cheerio or a browser?
| Cheerio with fetch | Headless browser | |
|---|---|---|
| Runs the page's JavaScript | No | Yes |
| What it downloads | The HTML document only | The page and everything it loads |
| Good for | Server-rendered pages, sitemaps, listings | Single-page apps, content behind clicks |
Keep to each site's terms and robots rules, and pause between requests. For larger jobs, our residential proxies and mobile proxies give your scraper a home or carrier IP in the country you choose, with a Residential Basic free trial; our web scraping API returns rendered pages when you would rather not run browsers yourself.


